API Documentation

Use the Nodeum APIs to automate your Data Management operations.

REST API

The REST API is available in Nodeum and the usage instructions are available here below :

Compatibility guidelines

The HTTP API is versioned with a single number, which is currently 2. This number symbolizes the major version number. Because of this, backward-incompatible changes require this version number to change.

The minor version isn’t explicit, which allows for a stable API endpoint. New features can be added to the API in the same version number.

New features and bug fixes are released in tandem with Nodeum. Major API version changes, and removal of entire API versions, are done in tandem with major Nodeum releases. All deprecations and changes between versions are in the documentation.

Current status

API version v2 is the latest.

How to use the API

API requests must include both api and the API version. . For example, the root of the v4 API is at /api/v2.

Valid API request

The following is a basic example of a request to the fictional nodeum.local endpoint:

curl "https://nodeum.local/api/v2/files"
The API uses JSON to serialize data. You don’t need to specify .json at the end of the API URL.
 

Request and response formats

For POST and PUT requests, the request body must be JSON, with the Content-Type header set to application/json.

For almost all requests, the response will be JSON.

Whether a request succeeded is indicated by the HTTP status code. A 2xx status code indicates success, whereas a 4xx or 5xx status code indicates failure. When a request fails, the response body is still JSON and contains additional information about the error.

 

Authentication

 API requests require authentication, or only return public data when authentication isn’t provided. 

There are several ways you can authenticate with the Nodeum API included :

Status codes

The API is designed to return different status codes according to context and action. This way, if a request results in an error, you can get insight into what went wrong.

Nodeum Public RestAPI

The following table gives an overview of how the API functions:

Request type Description
GET Access one or more resources and return the result as JSON.
POST Return 201 Created if the resource is successfully created and return the newly created resource as JSON.
GET / PUT Return 200 OK if the resource is accessed or modified successfully. The (modified) result is returned as JSON.
DELETE Returns 204 No Content if the resource was deleted successfully or 202 Accepted if the resource is scheduled to be deleted.

 

The following table shows the possible return codes for API requests.

Return values Description
200 OK The GET, PUT or DELETE request was successful, and the resource itself is returned as JSON.
202 Accepted The GET, PUT or DELETE request was successful, and the resource is scheduled for processing.
204 No Content The server has successfully fulfilled the request, and there is no additional content to send in the response payload body.
201 Created The POST request was successful, and the resource is returned as JSON.
304 Not Modified The resource hasn’t been modified since the last request.
400 Bad Request A required attribute of the API request is missing. For example, the title of an issue is not given.
401 Unauthorized The user isn’t authenticated. A valid user token is necessary.
403 Forbidden The request isn’t allowed. For example, the user isn’t allowed to delete a project.
404 Not Found A resource couldn’t be accessed. For example, an ID for a resource couldn’t be found.
405 Method Not Allowed The request isn’t supported.
409 Conflict A conflicting resource already exists. For example, creating a project with a name that already exists.
422 Unprocessable The entity couldn’t be processed.
429 Too Many Requests The user exceeded the application rate limits.
500 Server Error While handling the request, something went wrong on the server.

 

Offset-based Pagination

GitLab supports the Offset-based pagination. This is the default method and is available on all endpoints. Sometimes, the returned result spans many pages. When listing resources, you can pass the following parameters:

Parameter Description
page Page number (default: 1).
per_page Number of items to list per page (default: 20, max: 100).

 

Namespaced path encoding

If using path or namespaced API requests, make sure that the NAMESPACE/PATH is URL-encoded : / is represented by %2F.

 
 

About the OpenAPI specification

The OpenAPI specification (formerly called Swagger) defines a standard, language-agnostic interface to RESTful APIs. OpenAPI definition files are written in the YAML format, which is automatically rendered by the Nodeum website into a more human-readable interface.

For general information about the Nodeum APIs endoints : https://www.nodeum.io/resource-api#/