Overview¶

This section will provide guidance and usage on how to interact with Hubster’s APIs. The goal of Hubster is to provide a consistent and systematic approach across all our API resources, in terms of style, format and responses.

Hubster’s APIs are designed using REST principles and most of our payloads are structured using JSON. Any exception to this rule will be noted where necessary.

Note

Hubster APIs incorporate cross-origin resource sharing (CORS) whereby facilitating web applications to freely use our API in an authenticated and secure manner.

Environments¶

Below are the list of Hubster environments:

Identity	API Resource
Demo	https://demo-identity.hubster.io
Production	https://identity.hubster.io

Portal	API Resource
Demo	https://demo-portal-api.hubster.io
Production	https://portal-api.hubster.io

Engine	API Resource
Demo	https://demo-engine.hubster.io
Production	https://engine.hubster.io

Events	API Resource
Demo	https://demo-events.hubster.io
Production	https://events.hubster.io

Identity to API Resource Interaction¶

Below is a depiction on how a business application first obtains an access token, using Hubster’s identity service, which can later be used to make authenticated requests against API services, such as Hubster’s Portal, Engine and Events resources.

../_images/identity_api_resource_interactions.png

Note

API access tokens use the client_credential grant_type, Description you can only obtain a access tokens using client_ids and client_secrets respectively. These access tokens are longed-lived and last no longer than 30 days. When an access token expires, accessing an API resource yields an HTTP Status 401 - Unauthorized Access.

Furthermore, access tokens are only meant for their indented API resource. For example, if a business obtains an access token for the Portal API resource, the access token cannot be used for the to gain access to the Engine API resource, and likewise. These design was intentional as scopes for each API resource are vastly different. There’s an exception to this rule. Accessing the Events API requires an Engine access token.

To obtain an access_token, please refer to the Authentication API for more details.

Standard Error Response¶

Hubster’s standard error response model is consistent across all API resources. The only difference being are the actual error codes returned by each API resource.

Below is an example of a Bad Request (400) returned by the Portal API.

Response

{
    "status": 400,
    "errors": [
        {
            "code": 301,
            "description": "Property 'name' is required. (code: PRT000301)"
        },
        {
            "code": 206,
            "description": "Value '50000' is not valid. (code: PRT000206)"
        }
    ]
}

Property	Description
status	The HTTP Status code. This will value always equals header’s HTTP Status code.
errors	The list of errors.

Paginated Results¶

In some cases, Hubster may return a paginated response whereby, the business will need to re-query the next result, based on page number and page size. This is typically when certain GET requests may yield a large number of records.

Below is an example from Portal API resource returning Hubs as paginated response.

Response : 200 (OK)

{
    "pageNumber": 0,
    "pageSize": 50,
    "total": 2,
    "results": [
        {
            "hubId": "00000000-0000-0000-0000-0000000000a2",
            "tenantId": "00000000-0000-0000-0000-000000000001",
            "name": "Dev Hub 1",
            "description": "Dev Hub 1 (Websocket)",
            "statusId": 2000
        },
        {
            "hubId": "00000000-0000-0000-0000-0000000000a3",
            "tenantId": "00000000-0000-0000-0000-000000000001",
            "name": "Hubster Demo (blank)",
            "description": "Hubster Demo mainly used for Videos",
            "statusId": 2000
        }
    ]
}

Property	Description
pageNumber	The requested page number.
pageSize	The requested page size.
total	The total number of results across all pages. Note: the total number of items does not necessary equal the number of result items.
results	A list of response models returned by the API resource. Note: the result models may differ on per call basis.

HTTP Status Codes¶

Hubster API HTTP Status codes.

HTTP Status	Description
200	OK response. The body of the response will include the data requested.
201	OK response. The response will content no data.
400	Bad request. The body of the response will have more info.
401	Unauthorized. Token is invalid.
403	Forbidden. Access to the requested resource is forbidden.
404	Not found. Resource not found.
408	Timed out. The request timed out.
409	Conflict. The request caused a conflict.
410	Not available. The request is not available.
417	Expectation Failed. The operation was aborted.
429	Too many requests. API usage limit has been reached.
500	Internal server error. There was an internal issue with the service.
501	Not implemented. The request is not implemented.
503	Service unavailable. The service is unavailable.