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:
The following table shows the possible return codes for API requests.
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:
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