Nuxeo Core Developer Guide

What is Needed to Design a REST API

Updated: October 22, 2018 Page Information Edit on GitHub

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

List all directory entries

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 an entry

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

Search for entries

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

Update an entry

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

Create an entry

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

directoryEntry

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

directoryEntries

{
  "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

Execute an operation

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

2 months ago manonlumeau NXDOC-1650 fix about integrating changes, add mention on multiple attempts
2 years ago Solen Guitter 7
3 years ago Manon Lumeau 6
5 years ago Solen Guitter 5
5 years ago Damien Metzler 4
5 years ago Damien Metzler 3
5 years ago Damien Metzler 2
5 years ago Damien Metzler 1
History: Created by Damien Metzler

We'd love to hear your thoughts!

All fields required