API Methods

HTTP Methods

For simple API requests (managing single resources) the Core API supports standard HTTP request methods (HEAD, GET, POST, PATCH, PUT, and DELETE), which follow the specifications at RFC 9110 HTTP Semantics.

API Operations

In addition to the HTTP methods the Core API supports additional operations on resources that represent more specific operations on a specific resource or even a list of resources which are not covered by the HTTP methods.

They are also used to support bulk requests. This enables the client to manage several resources within a single request. This reduces the number of requests and simplifies the client logic for same kind of operations on same resources.

Operations are represented as a segment of the Core API URI schema in an HTTP POST request .

Operation Usecase Response body

query

fetches the resource(s collection)

only a list of IDs or TIDs without concrete resources or details

retrieve

fetches the resource(s)

the resource(s) with details

persist

create or update the resource(s)

the created/updated resource(s)

perform

to execute specific actions on resources. E.g. delete

if action was executed successfully and the results of the actions (depends on the actions)

API Actions

Dependent to the related resources Core API supports actions in perform operations that are performed on the defined resources. The actions are defined in the request body.

Actions give the flexibility to choose different kind of actions for different resource instances in 1 single request (if they are not interdependent). Which means that bulk processing is more flexible. In addition, the list of supported actions can be extended without necessity to change the URI.

Sample actions

  • delete

  • create

  • update

  • move

When to use what?

The Core API concept is very powerful and supports complex scenarios (bulk operations, reduction of network communications). On the other side this power is not needed in simpler scenarios. The following table helps to decide which API endpoint methods, operations and actions to be used when.

When What Why

you want to manage a single resource

use HTTP methods (if such exist) for your requirements

the requests are simpler. In best case with no or only query parameters and without (complex) request body. Then a request can also be easily executed in a browser or any HTTP client (cURL, Postman, …​).

you want to retrieve a list of resources (IDs or data)

use the operations query or retrieve

here you can differ between list of identifiers or concrete resource data and get a corresponding list

you want to create or update (change the resources' (meta-)data) a list of resources

use the operation persist

here you can create a list of resources within 1 request

you want to execute specialized actions on a list of resources

use the operation perform

to have the flexibility to perform different types of actions on a number list of resources.

With the flexibility to use bulk operations the error handling will become more complex. We support this by a response type that gives detailed information what operation/action for which resources went wrong. The client must be able to handle those responses.

So a design decision must be made dependent to your requirements whether to use simple endpoints for managing single resources or using additional operations/actions for managing a list of resources at once.

But you have the flexibility to mix them.

Welcome to the AI Chat!

Write a prompt to get started...