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:
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.
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:
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:
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
