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
Operator | Description |
---|---|
gt | greater than |
lt | less than |
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 resourcesnext
: 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 theSingle 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 errordetail
: 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."
}