RESTful API

Use the Nodeum APIs to automate your Data Management operations.

Nodeum supports different capabilities to handle Authorization process. The objective is to grant authenticated users access to resources by verifying whether they have access permissions or not. It also allows you to restrict access privileges by granting or denying specific access to authenticated users.

About RESTful API

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

• How to use the API.

• A list of the available resources and their endpoints, see REST API resources.

Compatibility guidelines

The HTTP API is versioned with a single number, which is currently 2. This number symbolizes the major version number.

Nodeum API version changes including entire API version removal are done in tandem with major Nodeum features releases and bug fixes. All deprecations and changes between versions are listed 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.

The following table gives an overview of how the API functions and status code are defined:

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

Nodeum API 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.

Use the API from an application

For executing an API requests from a client, it requires authentication, or only return public data when authentication isn’t provided.

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

• Basic Authentication

• Advanced Authentication

Basic authentication

Basic authentication is a simple authentication scheme. The client sends HTTP requests with the Authorization header that contains the word Basic followed by a space and a base64-encoded string username:password.

For example, to be authorized as admin/p@55w0rd the client would send this query:

$ curl -X GET -H "Accept: application/json" -H "Authorization: Basic YWRtaW46cEA1NXcwcmQ=" "https://nodeum.local/api/v2/tapes?limit=10"

Because base64 is easily decoded, Basic authentication is recommended to be used together with other security mechanisms such as HTTPS/SSL.

Advanced Authentication

Two options are available in this authentication schema: API keys and JWT Token.

The authentication is recommended to be used over HTTPS (SSL).

API keys

API keys authentication involves keys to handle the authentication. The client must send this key in the Authorization header that contains the word Bearer followed by a space and a provided key. Access can be restricted with a scope.

Configuration

In Nodeum, you have a security section where you can generate such kind of key. This is located in the menu:

System -> Configuration -> API Security

In the section, you can define the three following parameters:

• Name: This is the name of your choice.

• Controller: definition of controller, * is a wildcard to allow access to all endpoint.

• Action: define the action related to the controller, * is a wildcard to allow access to all endpoint.

Example, if we define as "Scope": Controller: files and Action: index, this means that the API key have only access to the controller files and the action as index.

The list of Controller and Action definitions are available in the Nodeum API documentation behind each endpoints.

Different Controller and Action can be defined in order to define the key with limited access.

Usage

The key must be provided in your request headers, for example, to be authorized with the key hv2ipsrv7y-JScJpV8h-x9w the client would send this query:

$ curl -X GET -H "Accept: application/json" -H "Authorization: Bearer hv2ipsrv7y-JScJpV8h-x9w" "https://nodeum.local/api/v2/tapes?limit=10" 

Bearer authentication (also called token authentication)

Provide your bearer token in the Authorization header when making requests to protected resources.

It is an HTTP authentication scheme that involves security tokens called bearer tokens. The name “Bearer authentication” can be understood as “give access to the bearer of this token.” The bearer token is a cryptic string, usually generated by the server in response to a login request.

The client must send this token in the Authorization header when making requests to protected resources: Authorization: Bearer <token>

The Bearer authentication has the requirement to have the Nodeum Administration console configured in JWT mode.

For example, to be authorized with the following JWT token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c the client would send this query:

$ curl --request GET \
 --url http://localhost/api/v2/files \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'

Use the API from a Browser

This access involved the concept of "Cross-origin resource sharing (CORS)" which is a browser mechanism to meet browser security requirements and send requests directly to Nodeum API endpoints.

Configuration

To configure CORS into Nodeum, you have to do login into your Nodeum Console and access the following menu:

System -> Configuration -> API Security Section

In the Cross-Origin section, you can define the three following parameters:

• Origins : definition of the DNS domain, * is the wildcard which will allow access from all domains.

• Path : definition of API endpoint path url , * is a wildcard to allow access to all endpoint.

• Methods : define the HTTP request method allow. GET / POST / PUT / DELETE can be defined, multiple selections are allowed.

Multiple rules can be configured to design the authentication you need.

Verify the API endpoint results

You can use Nodeum Console to validate any API call you want to use.

For doing this, you need to:

• Use a browser which include a development tool (e.g. Chrome, Firefox)

• Open the browser development tool

• Go into Nodeum console and execute the action you want to validate

• In the Network tab of the development tool (e.g. Inspector for Chrome), you see click in the API endpoint name. Show example below

• And then you can have access to the Header, Preview and Response

Verify an API endpoint

If this answer your demand, you can directly use the API endpoint call directly in your application.