Interoperability model for the Public Administration

Agenzia per l'Italia Digital & Team per la trasformazione digital (Italian administration)

API Design

Global design

General considerations on API design

API Lifecycle


How to ensure API governance (advertise, consistency, …)



How to handle long operations

Collection Resources


What is a collection (set) of resources


Data format

which data format use

Standards data

Which standard use for values like languages, countries, currencies, …

Error handling


How to handle errors

HTTP Methods

HTTP methods

General information about HTTP methods usage

  • Directions for use (REST)
    The REST service interface must use the HTTP verb most suitable for the operation as indicated in RFC 7231
  • Message broker
    Although, depending on the implementations, the different REST service interfaces for accessing message brokers differ in functionality offered and ways of modeling queues, topics / subscriptions, the following behaviors of HTTP methods can be abstracted


The GET method requests a representation of the specified resource. Requests using GET should only retrieve data and should have no other effect.


The HEAD method asks for a response identical to that of a GET request, but without the response body. This is useful for retrieving meta-information written in response headers, without having to transport the entire content.

  • Directions for use (REST)
    The REST service interface must use the HTTP verb most suitable for the operation as indicated in RFC 7231


The PATCH method applies partial modifications to a resource.


The PUT method requests that the enclosed entity be stored under the supplied URI. If the URI refers to an already existing resource, it is modified; if the URI does not point to an existing resource, then the server can create the resource with that URI.


The POST method requests that the server accept the entity enclosed in the request as a new subordinate of the web resource identified by the URI. The data POSTed might be, for example, an annotation for existing resources; a message for a bulletin board, newsgroup, mailing list, or comment thread; a block of data that is the result of submitting a web form to a data-handling process; or an item to add to a database.


The DELETE method deletes the specified resource.

HTTP Protocol


How to use and provide relevant caching informations

Content negociation and media types

How to describe your API data format and/or propose different formats (like json, yaml, xml atom, …)

HTTP Statuses

General information about HTTP statuses usage

HTTP Status Success

200 OK

Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action.

201 Created

The request has been fulfilled, resulting in the creation of a new resource.

204 No Content

The server successfully processed the request and is not returning any content.

HTTP Status User Error

404 Not Found

The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.

405 Method Not Allowed

A request method is not supported for the requested resource; for example, a GET request on a form which requires data to be presented via POST, or a PUT request on a read-only resource.

409 Conflict

Indicates that the request could not be processed because of conflict in the request, such as an edit conflict between multiple simultaneous updates.

415 Unsupported Media Type

The request entity has a media type which the server or resource does not support. For example, the client uploads an image as image/svg+xml, but the server requires that images use a different format.

422 Unprocessable Entity

The request was well-formed but was unable to be followed due to semantic errors.



How to use hypermedia

  • REST
    According to this approach, by accessing a resource, the server's response contains hyperlinks to other actions that can be performed on the resource
  • Use absolute URIs in the results



How to produce and/or propose API documentation

  • REST
    For these reasons the ModI imposes the use of OpenAPI v3. An OpenAPI file allows you to describe the entire interface (available endpoints and operations on each endpoint, input and output parameters for each operation, authentication methods, contact information, license, terms of use, etc.).

Performance and bandwidth

How to deal with high traffic or consumers with low bandwith



General informations about resources

  • The concept of service
    We can identify the types of properties, functional property, which expresses "what" we get from service; quality of the service, referring to characteristics (for example, delivery time) that specify benefits or perceived utility associated with the service; non-functional properties, expressing "how" the service is delivered to us.
  • CRUD Access to Resources

Retrieve resource partially

How to retrieve partially a resource

Retrieve resource

How to retrieve a resource

Create resource

How to create resources

Update resource

How to update a resource

Delete resource

How to delete resources



Security concerns