Key REST Concepts

The components of a REST operation are the following:
  • Resource Path
  • HTTP Verb
  • Body
  • Header

The URLs in the application’s REST URL name space provide the targets for the read (GET), write (POST), or update (PATCH) HTTP request types. The parameters of the REST operations always include a URL and an access token that authorizes access to the services. The following sections describe more about these concepts.

Resource Path

The resource path describes the object to be acted upon. It is in the form of a URL with the following structure:
BASE_URL + "/api/" + VERSION + "/" + REST

BASE_URL is the initial part of the URL for the Accelerator queue to access. For example, if the Accelerator NC_QUEUE environment variable was set to My_Test_Queue, then use the nc cmd vovbrowser command to obtain a BASE_URL.

The VERSION is the REST API version, currently v3.

REST is the remaining part of the URL that applies to the specific types of objects you will be referencing.

The resource path might look something like this when you are referencing the version information about the Accelerator queue scheduling server known as vovserver.
https://server.domain.myco.com:6330/api/v3/project/1/version

HTTP Verb

The verb describes the action to take regarding the resource.
POST
Creates a resource
GET
Retrieves one or more resources
PUT
Updates or controls a resource
PATCH
Updates a resource
DELETE
Deletes a resource

Body

The body of a REST request defines parameters and options that apply to the action being taken. A POST or PUT request has a body. A GET or DELETE request has no body. A Python dictionary data structure is the usual format for the body, and it consists of a set of keywords with associated values.

Header

The header contains metadata about the message being sent to the server which includes, importantly, an access token. REST HTTP requests are initiated across the network from a node other than the one on which the Accelerator server is running. The access token provides the assurance that the sender has permission to request the REST action on the server.

An authentication request type is available via a POST that supplies a username and password to the server, to which the server responds with the access token. When a REST request comes in later with this access token, the server can quickly and reliably extract the user identity and permissions as a prelude to processing the request. Accelerator REST utilizes a style of access token known as JSON Web Tokens (JWTs).