Quick Start

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.

Create REST enabled Role

The first thing is to configure security according to Security section:

  • Create a role that includes rest.enabled specific permission and grants permissions to read the user entity.

  • Assign the created role to the user that you want to use (like admin).

Start the application and test the REST API using the curl command-line tool.

Authenticate as a User

As the first request, you 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'

The response that you receive back contains a JSON document with information about the result of the authentication request:

HTTP/1.1 200
{
  "access_token": "CXE0w/9cOsnpSo8v2jEDoI8Qa3Y=",
  "token_type": "bearer",
  "refresh_token": "Hh2xCuZ7fgd35obagEBNGevF4ws=",
  "expires_in": 31535999,
  "scope": "rest-api",
  "OAuth2.SESSION_ID": "5C46CDF266E8C8C15372887830B74F59"
}

The attribute access_token contains the token that you can use for further requests as part of the Authorization Header.

Retrieve Entity List

Now that you performed a successful login on the API, the generic REST API endpoints can be used to load a list of users (replace <access_token> with the value obtained on the previous step):

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

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

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