Hybrid Core API v1

The Hybrid Core API refers to a Partner’s hybrid cores, related objects and resources.

You can use the API to query information about infrastructure of hybrid cores, e.g. get an overview of all physical hybrid core sites, an overview of all assets related to any hybrid core site or about a specific hybrid core’s physical site and it’s assets. Also you may consume the API to get an insight on CPU, memory and distributed/rocket/object storage resources workload and nodes application.

To interact with the Hybrid Core API, you need a user with access to a Partner account on gridscale.

The reference documentation can be found in the Partner Panel, with administrator-level access.

Auth

In order to use the API, you need to set your user UUID and a valid API Token in the header section of any request. Both are available via the web GUI of the in introduction above mentioned Partner Panel account you’ve access to.

Example for shell authentication headers:

	curl \
      -H "X-Auth-UserId: {USER_UUID}" \
	  -H "X-Auth-Token: {API_TOKEN}" \
    ...

You must replace {USER_UUID} and {API_TOKEN} with your personal user UUID and API key.`

Pagination

For pagination you can set an offset and/or a limit. You need to consider the syntax page[PARAMETER] where the PARAMETER placeholder is either named offset or limit. The value of the offset parameter defaults to value 0 if not explicitly set and the value of the limit parameter defaults to value 50 and is restricted to not reach this default value if explicitly set by the consumer of the API.

Filtering

For filtering you can set several parameters depending on the view/route you’ll request. You need to consider the syntax filter[PARAMETER] where the PARAMETER placeholder is needed to be replaced by filter parameter defined as being valid for respective view the request will be made on.

Following filters are available and allowed for GET on …

/hybrid-core/v1/sites

id string Filter by the ID of the site. It's name and unique identifier.

/hybrid-core/v1/sites/:site_id/assets

id	`string`	Filter by the ID of the asset. It's name and unique identifier.
node_type	`string`	Filter by the node type of the asset, which can either be `compute`, `distributed_storage` or `object_storage`.
node_type	`string`	Filter by the status of the asset, e.g. `active`, `staged` or `failed`.

Sorting

For sorting you can use query parameters to rule the order of the output you’ll request. You need to consider the syntax sort[PARAMETER] where the PARAMETER placeholder is needed to be replaced by sorting parameter defined as being valid for respective view the request will be made on. The sorting defaults to ascending order, which is represented by the query parameter value +. If you want to have the responded hits ordered descending, then you explicitly need to set the query parameter and assign the - as value.

Additionally, it is worth mentioning that the sorting by asset resource (memory and storage) usage covers sorting by percentage and raw value where the sorting by percentage always precedes the sorting by the raw value. So the sorting by resource usage covers a relative order view considering both, the percentage and the raw value.

Following sorting is available and allowed for GET on …

/hybrid-core/v1/sites

id	Sort by the ID of the site. It's name and unique identifier.

/hybrid-core/v1/sites/:site_id/assets

id	Sort by the ID of the asset. It's name and unique identifier.
node_type	Sort by the node type of the asset.
status	Sort by the status of the asset.
memory_usage	Sort by the asset's RAM usage. The ordering affects assets of compute node type.
storage_usage	Sort by the asset's storage usage. The ordering affects usage of three storage types, namely distributed, object and rocket (local) storage where the latter mentioned belongs to compute node type assets and the two previously embody node type assets of their own kind.

The ordering between the sort query parameters is affected by their sequential arrangement. Finally and already mentioned above, all sort query parameters (e.g. for GET /sites/:site_id/assets at least sort[id], sort[node_type], sort[status], sort[memory_usage] and sort[storage_usage]) default to ascending ordering if not set. So the sequential arrangement of the query parameters in the request rule the priority. E.g. if sort[storage_usage] would be set and sort[id] wouldn’t explicitly bet set, then still the ascending ordering by ID would be at hand, but would be dominated by the ascending ordering by storage usage.

Example requests

You can fetch an OpenAPI spec file at /api/v1/doc via

    $ curl -s \
      -H 'Content-Type: application/json' \
      -H "X-Auth-UserId: {USER_UUID}" \
      -H "X-Auth-Token: {API_TOKEN}" \
      -X GET "https://api.gridscale.io/hybrid-core/v1/doc" | jq

If you want to get the list of all hybrid core sites you need to request like

    $ curl -s \
      -H 'Content-Type: application/json' \
      -H "X-Auth-UserId: {USER_UUID}" \
      -H "X-Auth-Token: {API_TOKEN}" \
      -X GET "https://api.gridscale.io/hybrid-core/v1/sites" | jq

If you need information about a specific site, you either can use the id as filter query parameter with syntax filter[id] in curl command of above displayed code snippet or make a GET request on a site’s detail view as shown in followong curl-command where site with ID vv10 is wanted to get a view on and is placed as path parameter at the end of the URL.

    $ curl -s \
      -H 'Content-Type: application/json' \
      -H "X-Auth-UserId: {USER_UUID}" \
      -H "X-Auth-Token: {API_TOKEN}" \
      -X GET "https://api.gridscale.io/hybrid-core/v1/sites/vv10" | jq

To inquire the list of all assets belonging to a specific hybrid core site you can do

    $ curl -s \
      -H 'Content-Type: application/json' \
      -H "X-Auth-UserId: {USER_UUID}" \
      -H "X-Auth-Token: {API_TOKEN}" \
      -X GET "https://api.gridscale.io/hybrid-core/v1/sites/xy01/assets" | jq

referring to the site with ID xy01 in the URL path.

Running the same request using pagination then would look like

    $ curl -s \
      -H 'Content-Type: application/json' \
      -H "X-Auth-UserId: {USER_UUID}" \
      -H "X-Auth-Token: {API_TOKEN}" \
      -X GET "https://api.gridscale.io/hybrid-core/v1/sites/xy01/assets?page\[limit\]=50&page\[offset\]=150" | jq

Same as for sites you also can have a look on just a specific asset either using the id as filter query parameter with syntax filter[id] at GET on the view with response holding several items or execute a GET request on an asset’s detail view using the ID of the site the asset belongs to as well as the ID of the asset as path paramters following the /hybrid-core/v1/sites/:site_id/assets/:asset_id route pattern.

To access the resources view of a site, e.g. with ID vv10, you would need to query as presented in code snippet below.

    $ curl -s \
      -H 'Content-Type: application/json' \
      -H "X-Auth-UserId: {USER_UUID}" \
      -H "X-Auth-Token: {API_TOKEN}" \
      -X GET "https://api.gridscale.io/hybrid-core/v1/sites/vv10/resources" | jq

Hybrid Core API v1

Auth#

Pagination#

Filtering#

Sorting#

Example requests#

Auth

Pagination

Filtering

Sorting

Example requests