18. Digital Rebar Provision API

All API calls are available under /api/v3 based on the Digital Rebar API convention.

18.1. Example API Documentation

Below is a list of example documentation articles on how to use the API.

18.2. API Call Documentation (swagger.json)

Digital Rebar API documentation is dynamically generated an with each Digital Rebar endpoint in the form of a swagger.json file.

The Swagger specification file is introspectable for clients via [endpoint url]/swagger.json and for humans via the Swagger UX built into all DRP endpoints at [endpoint url]/swagger-ui.

For more details, see Swagger UI.

18.3. API PUT vs PATCH

RackN strongly recommends API consumers to use PATCH wherever possible instead of PUT. PATCH allows API calls to change specific object fields and may include tests to prevent race conditions.

For example, the Digital Rebar CLI (drpcli) and RackN UX use JSON PATCH (https://tools.ietf.org/html/rfc6902) instead of PUT extensively. PATCH allows atomic field-level updates by including tests in the update. This means that simulataneous upates do not create “last in” race conditions. Instead, the update will fail in a predictable way that can be used in scripts.

The DRPCLI facilitates use of PATCH for atomic operations by allowing scripts to pass in a reference (aka pre-modified) object. If the -r reference object does not match then the update will be rejected.

18.4. API Filters

The API includes index driven filters for large deployments that can be used to pre-filter requests from the API.

The list of available indexes is provided by the /api/v3/indexes and /api/v3/indexes/[model] calls. These objects provide a list of all keys that can be used for filters with some additional metadata. Additionally, the Meta data field on objects can be used in filters as welll, e.g. Meta.color=pink.

To use the index, simply include one or more indexes and values on the request URI. For example:

/api/v3/machines?Runnable=true&Available=true

The filter specification allows more complex filters using functions:

  • Equal (either works)

    • =

    • Eq(Value)

  • Less Than: Lt(Value)

  • Less or Equal: Lte(Value)

  • Greater Than: Gt(Value)

  • Greater or Equal: Gte(Value)

  • Not Equal: Ne(Value)

  • Regular Expression: Re(Value)

  • Ranges:

    • Between(Value1,Value2) (edited)

    • Except(Value1,Value2)

The query string applies ALL parameters are to be applied (as implied by the & separator). All must match to be returned.

18.5. Filtering by Param Value

The API includes specialized filter behavior for Params that allows deep searching models for Param values.

To filter Machines or Profiles by Param values, pass the Param name and value using the normal Field filter specification. When the Field is not found, the backend will search model’s Params keys and evalute the filter against the Param value.

18.6. Filtering by Aggregated Param Value

By default, the API does NOT aggregate the values of the parameters through the attached profiles or global profile. By adding the aggregate=true string to the Query string in the URL, the API will apply the filter against an aggregated set of parameters when searching for the object. Additionally, the Param field of the object will contain an aggregated set of parameters as well.

18.7. Filtering with Template Expansion

The API can also use Template functions to enhance searches. Using the raw=<filter string>, a raw filter string can be sent to the server for expansion and processing. The raw field will be additive to the other query string filters sent. Multiple filter elements can be sent in a space delimited format. Here are some examples:

18.8. Leveraging Multi-Site Proxy Forwarding

In the Manager Architecture, API calls to a DRP manager for remote objects are automatically forwarded to the correct attached endpoint. This allows operators to make API calls to remote endpoints from a centralized manager without knowing the actual owner of the object. The owning endpoint can be determined for any object by inspecting its Endpoint property.

For most cases, no additional information or API notation is required to leverage this functionality. The exception is creating objects on attached endpoints. The create (aka POST) case requires API callers to specify the target remote endpoint (the endpoint must be registered or the request will be rejected) to the manager.

To make an explicit API proxy call, prefix the path of the request with the endpoint identity. For example:

/[target endpoint id]/api/v3/machines

This pattern is also invoked by with the -u flag in the DRPCLI.

NOTE: Multi-site is a licensed feature available in DRP v4.5+ and must be enabled for the endpoint.

18.9. Payload Reduction (slim)

Since Params and Meta may contain a lot of data, the API supports the ?slim=[Params,Meta] option to allow requests to leave these fields unpopulated. If this data is needed, operators will have to request the full object or object’s Params or Meta in secondary calls.

/api/v3/machines?slim=Params,Meta

Only endpoints that offer the slim-objects feature flag (v3.9+) will accept this flag.

18.10. Exploration with Curl

You can also interact with the API using curl. The general pattern is:

# option 1: basic auth user:password
curl -X <method> -k -u <username>:<password> -H 'Content-Type: application/json' -H 'Accept: application/json' https://<endpoint addr>:<port>/api/v3/<opject type>/<object ID>

# option 2: basic auth with token
export RS_TOKEN=$(drpcli -P <password> users token <username>)
curl -X <method> -k --header 'Authorization: Bearer $RS_TOKEN' -H 'Content-Type: application/json' -H 'Accept: application/json' https://<endpoint addr>:<port>/api/v3/<opject type>/<object ID>

In the remainder of this section, <object type> refers to the lower case, pluralized version of the type of object. This is bootenvs for boot environments, workflows for workflows, machines for machines, and so on. <object id> refers to the unique identifier for this object, which is generally the Name, ID or Uuid field of an object. You can also use any unique index in this field, in the form of <index name>:<value>. A common one to use is Name:machine.name for Machine objects instead of the Uuid.

The API follows the usual REST guidelines:

  • HEAD /api/v3/<object type> gets you headers containing basic information about how many of <object type> are present in the system. You can use filters on this request.

  • GET /api/v3/<object type> lists all of the objects of the requested type. The result is a JSON array. You can use filters on this request.

  • POST /api/v3/<object type> is a request to create a new object. The body of the payload should be valid JSON for the object type.

  • GET /api/v3/<object type>/<object id> fetches the request object.

  • HEAD /spi/v3/<object type>/<object id> tests to see if the requested object exists.

18.11. API Exception & Deprecation Notes

There are times when the API and models have exceptions or changes that do not follow the normal pattern. This section is designed to provide a reference for those exceptions.

This section is intended to provide general information about and functional of the API. We maintain this section for legacy operators, when possible avoid using deprecated features!

Machines.Profile (deprecated by flag: profileless-machine)

What would otherwise be Machine.Params is actually embedded under Machines.Profile.Params. This deprecated composition simplifies that precedence calculation for Params by making Machines the top of the Profiles stack. All the other fields in the Machines.Profile are ignored.

Error

Unable to process URL: https://rebar-catalog.s3-us-west-2.amazonaws.com/swagger.json. Please check that the URL is a valid Swagger api-docs URL and it is accesible