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:
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 |
|---|---|
| Access one or more resources and return the result as JSON. |
| Return |
| Return |
| Returns |
The following table shows the possible return codes for API requests.
| Return values | Description |
|---|---|
| The |
| The |
| The server has successfully fulfilled the request, and there is no additional content to send in the response payload body. |
| The |
| The resource hasn’t been modified since the last request. |
| A required attribute of the API request is missing. For example, the title of an issue is not given. |
| The user isn’t authenticated. A valid user token is necessary. |
| The request isn’t allowed. For example, the user isn’t allowed to delete a project. |
| A resource couldn’t be accessed. For example, an ID for a resource couldn’t be found. |
| The request isn’t supported. |
| A conflicting resource already exists. For example, creating a project with a name that already exists. |
| The entity couldn’t be processed. |
| The user exceeded the application rate limits. |
| 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 number (default: |
| Number of items to list per page (default: |
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:
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:
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:
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
If this answer your demand, you can directly use the API endpoint call directly in your application.
Last updated
