What is Needed to Design a REST API

Developers need some information to know what to do when adding a new REST endpoint. Basically a REST request is made of several parts:

• The URL: this locates the resource;
• A verb: GET, PUT, POST, DELETE;
• Some headers;
• Some Accept/Consume types;
• Query params.

And it actually returns some objects that have some types.

Now Nuxeo adds some other paradigms:

• entity-type: It is the type of the entity and is part of the response body. It MUST follow camelCase notation.

• adapters: It is a URI fragment that is added to a resource URL and denotes an 'adaptation' of the resource. It is compatible with a given set or resource types.

Naming Conventions

• Endpoint names should not be abbreviated (i.e.: directory, user ).
• Endpoint names should be singular (directory not directories).
• Adapter names MUST start with an @.
• Adapter names should be singular.
• Adapter names MAY BE abbreviated ( @wf for workflow, @op for operation).

How to Specify

In order to specify correctly an API endpoint, the documentation should specify the elements below.

The List of URLs With Actions

A URL is defined by the verb followed by a URL with parameter between braces. After that, we use the Javadoc notation to describe parameters, return types and exceptions:

• @param: The type of the entity passed as the body (for PUT and POST);
• @pathparam: Describes a path parameter referred by the URL;
• @queryparam: Describes a parameter of the query string: i.e. /search?q=john.
• @return: Defines the model that is returned;
• @exception: Defines each status code with its signification.

The List of Models

Models defined by return type should be described with their JSON representation. Each model should refer an entity-type. The notation used to describe the entity-type MUST be camelCase.

Complete Samples

Directory Endpoint

The directory endpoint exposes the internal directory services APIs

URLs

GET /directory/{directoryName}
@pathparam {directoryName} the name of the directory
@queryparam key value map to a directory search filter
@return directoryEntries
@exception : 404 directory not found
@exception : 500 server error

GET /directory/{directoryName}/{entryId}
@pathparam {directoryName} the name of the directory
@pathparam {entryId} the id of the entry to fetch
@return directoryEntries
@exception : 404 entry or directory not found
@exception : 500 server error

GET /directory/{directoryName}/@search
@pathparam the name of the directory
@queryparam key value map to a directory search filter
@return directoryEntries
@exception : 404 entry or directory not found
@exception : 500 server error

PUT /directory/{directoryName}/{entryId} :
@param a directoryEntry
@return directoryEntry
@exception : 404 entry or directory not found
@exception : 403 not allowed to edit entry
@exception : 500 server error

POST /directory/{directoryName}
@param a directoryEntry
@return 201 directoryEntry
@exception : 404 entry or directory not found
@exception : 403 not allowed to edit entry
@exception : 500 server error

List of Models

{
  "entity-type": "directoryEntry",
  "directoryName": "userDirectory",
  "properties": {
    "lastName": "",
    "username": "Administrator",
    "email": "[email protected]",
    "company": "",
    "firstName": "",
    "password": "Administrator",
    "groups": [
      "administrators"
    ]
  }
}

{
  "entity-type": "directoryEntries",
  "directoryName": "userDirectory",
  "entries": [
    {
      "entity-type": "directoryEntry",
      "directoryName": "userDirectory",
      "properties": {
        "lastName": "",
        "username": "Administrator",
        "email": "[email protected]",
        "company": "",
        "firstName": "",
        "password": "Administrator",
        "groups": [
          "administrators"
        ]
      }
    },
...
  ]
}

Operation Adapter

Adapts a resource by running an automation operation/chain on it.

This adapter is compatible with resource of type:

• document,
• documents,
• blob,
• blobs.

URLs

POST {RESOURCE_URL}/@op/{operationId} :
@pathparam the operation/chain id
@return document, documents, blob, blobs (depending on the operation/chain return type)
@exception : 404 resource or operation not found
@exception : 403 not allowed to run that operation
@exception : 400 operation not compatible with resource
@exception : 500 server error