Adding Content Item ApiController.cs endpoints documentation

src/docs/reference/modules/Contents/README.md

@@ -129,6 +129,136 @@ Well known properties include
     To log shapes call `@Orchard.ConsoleLog(Model.Content as object)` after calling `@await DisplayAsync(Model.Content)`
     This will allow the shape to execute, and populate the alternates for any child shapes.
 
+## Contents Module RESTful Web API
+
+The `OrchardCore.Contents` module provides RESTful API endpoints via [`ApiController`](https://github.com/OrchardCMS/OrchardCore/blob/main/src/OrchardCore.Modules/OrchardCore.Contents/Controllers/ApiController.cs) featuring endpoints to manage _content items_. These endpoints allow for operations such as retrieving, creating, updating, and deleting single content item instances. Access to these endpoints requires authentication and appropriate user role permissions.
+
+### Useful modules and libraries
+
+1. We suggest to use the docs about the [GraphQL module](https://docs.orchardcore.net/en/main/docs/reference/modules/Apis.GraphQL/), to be used for querying content items.
+2. There's a [Swagger module](https://github.com/OrchardCoreContrib/OrchardCoreContrib.Modules/blob/main/src/OrchardCoreContrib.Apis.Swagger/README.md) made by the community and allows you to create APIs documentations using Swagger.
+3. Lombiq provide [client library](https://github.com/Lombiq/Orchard-Core-API-Client) for communicating with the Orchard Core web APIs.
+
+### Activating the "OpenId Authorization Server" and "OpenId Token Validation" Features, and setting User Roles
+
+To utilize the Orchard Core ApiController endpoints, user accounts must authenticate using the OAuth 2 standard by activating and configuring the "OpenId Authorization Server" and "OpenId Token Validation" features. Detailed configuration steps can be found in the [OpenId Authorization Server documentation](https://docs.orchardcore.net/en/main/docs/reference/modules/OpenId/#authorization-server) and the [OpenId Token Validation documentation](https://docs.orchardcore.net/en/main/docs/reference/modules/OpenId/#token-validation).
+
+It is usually better to create a dedicated user for performing API calls, to maintain control over user rights, and to easily activate/deactivate the API user. The `OrchardCore.OpenId` feature allows setting these user role permissions from "Roles > Edit (User)":
+
+- View and edit the OpenID Connect client settings
+- View and edit the OpenID Connect server settings
+- View and edit the OpenID Connect validation settings
+- View, add, edit, and remove the OpenID Connect applications
+- View, add, edit, and remove the OpenID Connect scopes
+
+### Contents API Controller Endpoints
+
+#### <span style="color:blue">GET /api/content/{contentItemId} </span>
+
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+| contentItemId | path | The ID of the Content Item to be retrieved | Yes | string |
+
+##### Responses
+
+| Code | Description |
+| ---- | ----------- |
+| 200 | Success |
+
+***
+
+#### <span style="color:blue">GET /api/queries/{name} </span>
+
+##### Parameters
+
+!!! note
+    This endpoint can only be used when the GraphQL feature is active.
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+| name | path | The name of the query available in the Query panel | Yes | string |
+
+##### Responses
+
+| Code | Description |
+| ---- | ----------- |
+| 200 | Success |
+
+***
+
+#### <span style="color:green">POST /api/content </span>
+
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+|  | payload | The content item model to be updated | Yes | Json |
+
+##### Body payload example
+
+```json
+{
+  "contentItem": "string",
+  "id": 0,
+  "contentItemId": "string",
+  "contentItemVersionId": "string",
+  "contentType": "string",
+  "published": true,
+  "latest": true,
+  "modifiedUtc": "2024-03-14T11:40:20.331Z",
+  "publishedUtc": "2024-03-14T11:40:20.331Z",
+  "createdUtc": "2024-03-14T11:40:20.331Z",
+  "owner": "string",
+  "author": "string",
+  "displayText": "string"
+}
+```
+
+> This payload example model was obtained using the GraphiQL, panel available in the Admin backoffice: _Configuration_ > _GraphiQL_. In this [video](https://www.youtube.com/watch?v=8SbW3TLNhF0) you can find an overview on how to use GraphiQL. 
+
+##### Responses
+
+| Code | Description |
+| ---- | ----------- |
+| 200 | Success |
+
+***
+
+#### <span style="color:green">POST /api/queries/{name} </span>
+
+##### Parameters
+
+!!! note
+    This endpoint can only be used when the GraphQL feature is active
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+| name | path | The name of the query available in the Query panel | Yes | string |
+
+##### Responses
+
+| Code | Description |
+| ---- | ----------- |
+| 200 | Success |
+
+***
+
+#### <span style="color:red">DELETE /api/content/{contentItemId}</span>
+
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ---- |
+| contentItemId | path | The ID of the Content Item to be deleted | Yes | string |
+
+##### Responses
+
+| Code | Description |
+| ---- | ----------- |
+| 200 | Success |
+
 ## GraphQL
 
 The contents module provides a feature to provide GraphQL queries for content items.