Getting Started with REST

This section contains a practical guide on getting started with the generic REST API.

Let’s consider that we want to retrieve information about orders in the application through the REST API.

First, add generic REST to your project according to the installation section and start the application.

Allow User Access via REST

When interacting with the application via the REST API, you always do this in the context of a particular user. Therefore, we need to grant the user the ability to access the application via the API.

You need to assign the predefined REST: minimal access role (with rest-minimal code) to the user that you want to use for the API interactions. The admin user already has all permissions because of the system-full-access role.

Authenticate against the API

In this example, we will use the curl command-line tool for interacting with the REST API.

Before loading data or sending data to the API, we need to perform a login or Authentication request. Use the following cURL command to do the request:

curl -X POST http://localhost:8080/oauth/token \
   --basic --user client:secret \
   -H "Content-Type: application/x-www-form-urlencoded" \
   -d "grant_type=password&username=admin&password=admin"
On Windows, remove \ symbols and write the command in a single line.

The HTTP 200 indicates a successful response which contains a JSON document with information about the result of the authentication request:

HTTP/1.1 200
{
  "access_token": "zmSIwB4_9he68yrNsHC5N1agktA",
  "token_type": "bearer",
  "refresh_token": "Tm3_v0T-eeYS6URZgoi4e_r-ub8",
  "expires_in": 31535999,
  "scope": "rest-api",
  "OAuth2.SESSION_ID": "5C46CDF266E8C8C15372887830B74F59"
}

The attribute access_token is the token you can use for further requests as part of the Authorization Header. It acts as a temporary credential that grants you access to the application on the user’s behalf.

Retrieve Entity List

With the access token you can use the generic REST API endpoints to load a list of users (replace <access_token> with the value obtained on the previous step). In this case, we will fetch all the users that are present in the application through the Entities API:

curl -X GET http://localhost:8080/rest/entities/User \
    -H "Authorization: Bearer <access_token>"

The response will contain all users that are available in the application:

HTTP/1.1 200
[
  {
    "_entityName": "User",
    "_instanceName": "  [admin]",
    "id": "60885987-1b61-4247-94c7-dff348347f93",
    "version": 1,
    "active": true,
    "username": "admin"
  }
]