# RESTful API Guide 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](https://www.nodeum.io/resource-api). ## 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: ```bash $ 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: {% code overflow="wrap" %} ```bash $ curl -X GET -H "Accept: application/json" -H "Authorization: Basic YWRtaW46cEA1NXcwcmQ=" "https://nodeum.local/api/v2/tapes?limit=10" ``` {% endcode %} {% hint style="info" %} Because base64 is easily decoded, Basic authentication is recommended to be used together with other security mechanisms such as HTTPS/SSL. {% endhint %} ### **Advanced Authentication** Two options are available in this authentication schema: API keys and JWT Token. {% hint style="info" %} The authentication is recommended to be used over HTTPS (SSL). {% endhint %} #### **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.* {% hint style="info" %} The list of Controller and Action definitions are available in the Nodeum API documentation behind each endpoints. {% endhint %} 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 ` 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: {% code overflow="wrap" %} ```bash $ curl --request GET \ --url http://localhost/api/v2/files \ --header 'Accept: application/json' \ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' ``` {% endcode %} ## 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.