Getting Started

The Gainfully API provides programmatic access to the data in our system. For example, a Relationships endpoint to retrieve a list of members in your organization or Events endpoints to fetch shared content.

Authentication

To access Gainfully API, a API key is required in the HTTPS Authorization header.

curl --location --request GET 'https://api.gainfully.com/v1.0/relationships/' \
--header 'Content-Type: application/json' \
--header 'Authorization: API_KEY'

Retrieving resources

The Gainfully API offers predictable and resource-oriented URLs. A single resource is accessed by a unique identifier of an object GET /example-resource/:id while a list of resources is fetched by resource type GET /example-resource/.

Ordering

Sorting is possible when retrieving resources by using the ordering query parameter.
Any attributes of the resource can be used when sorting the response. To reverse the sorting order, the attribute name must be preceded by -

• Example: GET /v1.0/content?ordering=name (Resource objects are sorted by name in alphabetical order)
• Example: GET /v1.0/content?ordering=-name (Resource objects are sorted by name in reverse alphabetical order)

Pagination

When retrieving multiple resource objects, the result is always paginated.

The Gainfully API uses the limit and offset pagination model where the limit represents the number of objects retrieved per page, while the offset indicates the starting position of the query in relation to the complete set of unpaginated items.

Paginated responses provide urls for the next and previous pages where available, as well as a total number of objects. ( See Multiple resource response for the response format )

The pagination parameters are:

• limit: Number of objects to retrieve in the response.
• offset: Starting position of the query in relation to the complete set of unpaginated items.

Filtering

Resources support filtering by certain attributes ( documented for each resource ), which allow for easier fetching of desired resources, and filters are given in the URL as query parameters.

Filter parameter names are formed by prefixing filter__ to the field name.

• Example: GET /v1.0/relationships?filter__type=4

Certain filters allow for operators through the __ symbol. For example, timestamps can allow for relational operators.

• Example: GET /v1.0/content?filter__created_at__gt=1572274684

Sparse fieldsets

When retrieving resource objects, it is possible to request only specific fields by using the fields parameter. This parameter takes a value of comma-separated field names.

• Example: GET /v1.0/content?fields=name,message

Document Structure

Single resource response

Retrieving a resource by a specific id will yield a single resource object.

The top-level document contains all attributes of the resource object. This includes the id attribute that uniquely identifies the object unless stated otherwise.

Multiple resource response

Retrieving multiple resources yields a paginated list of resource objects.

The top level of the document contains the following attributes:

• count: Total number of resources
• next: URL for the next page of resources ( if available )
• previous: URL for the previous page of resources ( if available )
• results: List of resource objects. The resource objects inside the list follow the same structure from the Single resource response section.

Error response

Errors have a specific document structure which is accompanied by an appropriate HTTP code to allow for easier error handling.

Resources have their specific error codes documented inside their documentation pages.
An error response contains the following attributes:

• field: Attribute name inside the body of a request which caused the error - error_code: String-based code for the error
• detail: Description of the error

{
    "field": "name",
    "error_code": "required",
    "detail": "This field is required."
}

Rate limiting

The rate limiting of the API is done on a per-token basis. When the rate limit is reached, the following response is returned:

Status: 429 Too Many Requests
{
  "field": null,
  "error_code": "throttled",
  "detail": "Request was throttled. Expected available in x seconds."
}