Nodeum REST API
Connect Production Pipelines & Business Workflows with your Storage.
Quickly.
Use the Nodeum APIs to automate your Data Management operations.
The REST API is available in Nodeum and the usage instructions are available here below :
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.
API version v2 is the latest.
API requests must include both api and the API version. . For example, the root of the v4 API is at /api/v2.
The following is a basic example of a request to the fictional nodeum.local endpoint:
curl "https://nodeum.local/api/v2/files"
.json at the end of the API URL.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.
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 :
Basic authentication is a simple authentication scheme. The client sends HTTP requests with the Authorization header that contains the word Basic word followed by a space and a base64-encoded string username:password.
For example, to authorize as admin / p@55w0rd the client would send this way:
curl -X GET -H "Accept: application/json" -H "Authorization: Basic YWRtaW46cEA1NXcwcmQ=" "https://nodeum.local/api/v2/tapes?limit=10"
Bearer authentication also called token authentication is an HTTP authentication scheme that involves security tokens called bearer tokens. The client must send this token in the Authorization header when making requests to protected resources.
In Nodeum, you have a security section where you can generate such kind of token. This is located inthe menu System/Configuration/API Security:
Different Controller and Action can be defined in order to define token with limited access.
The token must then be provided in your request headers this way.:
curl -X GET -H "Accept: application/json" -H "Authorization: Bearer HGiAOZkYt858poQNqEu_PA" "https://nodeum.local/api/v2/tapes?limit=10"
The Cross-Origin section allow security configuration to do API call from browser.
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.
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. |
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). |
If using path or namespaced API requests, make sure that the NAMESPACE/PATH is URL-encoded : / is represented by %2F.
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#/
