Content Manipulation

The restapi does not only expose content objects via a RESTful API. The API consumer can create, read, update, and delete a content object. Those operations can be mapped to the HTTP verbs POST (Create), GET (Read), PUT (Update) and DELETE (Delete).

Manipulating resources across the network by using HTTP as an application protocol is one of core principles of the REST architectural pattern. This allows us to interact with a specific resource in a standardized way:

Creating a Resource with POST

To create a new resource, we send a POST request to the resource container. If we want to create a new document within an existing folder, we send a POST request to that folder:

POST /news HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk
Content-Type: application/json

{
  "@type": "Page",
  "title": "My News Item",
  "description": "News Description"
}

By setting the ‘Accept’ header, we tell the server that we would like to receive the response in the ‘application/json’ representation format.

The ‘Content-Type’ header indicates that the body uses the ‘application/json’ format.

The request body contains the minimal necessary information needed to create a document (the type and the title). You could set other properties, like “description” here as well.

Successful Response (201 Created)

If a resource has been created, the server responds with the 201 Created status code. The ‘Location’ header contains the URL of the newly created resource and the resource representation in the payload:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "title": "My News Item",
  "description": "News Description",
  "@id": "http://localhost:8000/news/my-news-item",
  "@type": "Page",
  "id": "my-news-item",
  "created": "2022-04-08T16:00:00.000Z",
  "modified": "2022-04-08T16:00:00.000Z",
  "UID": "a95388f2-e4b3-4292-98aa-62656cbd5b9c",
  "is_folderish": true,
  "owner": "admin",
  "review_state": "private",
  "lock": {
    "locked": false,
    "stealable": true
  }
}

Unsuccessful Response (400 Bad Request)

If the resource could not be created, for instance because the title was missing in the request, the server responds with 400 Bad Request:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "message": "Required field(s) missing."
}

The response body can contain information about why the request failed.

Reading a Resource with GET

After a successful POST, we can access the resource by sending a GET request to the resource URL:

GET /news HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

Successful Response (200 OK)

If a resource has been retrieved successfully, the server responds with 200 OK:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "title": "News",
  "blocks": {
    "79ba8858-1dd3-4719-b731-5951e32fbf79": {
      "@type": "title"
    }
  },
  "description": "News Items",
  "blocks_layout": {
    "items": [
      "79ba8858-1dd3-4719-b731-5951e32fbf79"
    ]
  },
  "items": [],
  "@id": "http://localhost:8000/news",
  "@type": "Folder",
  "id": "news",
  "created": "2022-04-02T20:22:00.000Z",
  "modified": "2022-04-02T20:22:00.000Z",
  "effective": "2022-04-02T20:22:00.000Z",
  "UID": "32215c67-86de-462a-8cc0-eabcd2b39c26",
  "owner": "admin",
  "is_folderish": true,
  "review_state": "published",
  "lock": {
    "locked": false,
    "stealable": true
  }
}

For folderish types, their childrens are automatically included in the response as items.

Unsuccessful response (404 Not Found)

If a resource could not be found, the server will respond with 404 Not Found:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "Not found: /random"
}

GET Responses

Possible server reponses for a GET request are:

• 200 OK
• 404 Not Found
• 500 Internal Server Error

Updating a Resource with PATCH

To update an existing resource we send a PATCH request to the server. PATCH allows to provide just a subset of the resource (the values you actually want to change).

If you send the value null for a field, the field’s content will be deleted. Note that this is not possible if the field is required.

PATCH /news/my-news-item HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk
Content-Type: application/json

{
  "title": "My New News Item"
}

Successful Response (204 No Content)

A successful response to a PATCH request will be indicated by a 204 No Content response by default:

HTTP/1.1 204 No Content

Removing a Resource with DELETE

We can delete an existing resource by sending a DELETE request:

DELETE /news/my-news-item HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

A successful response will be indicated by a 204 No Content response:

HTTP/1.1 204 No Content

DELETE Repsonses

• 204 No Content
• 404 Not Found (if the resource does not exist)
• 405 Method Not Allowed (if deleting the resource is not allowed)
• 500 Internal Server Error

Reordering sub resources

The resources contained within a resource can be reordered using the ordering key using a PATCH request on the container.

Use the obj_id subkey to specify which resource to reorder. The subkey delta can be ‘top’, ‘bottom’, or a negative or positive integer for moving up or down.

PATCH /news HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk
Content-Type: application/json

{
  "ordering": {"obj_id": "my-news-item", "delta": "top"}
}