Overview

Introduction

Infinity API is REST-based, returns JSON-encoded responses, and uses standard HTTP verbs, status codes, and authentication.

Authentication

Infinity API authentication is token-based. Authentication is passed in the Authorization header with a value set to Bearer token.

We're in the process of implementing OAuth Authorization Code Grant to allow integration with third-party applications. In the mean time, you can use Personal Access Tokens to access your data.

important

Your Access Token can give access to your private data and should be treated like a password. Keep them secure and never share with anyone, or other third-party applications.

Personal Access Tokens never expired. If you think someone have access to any of your tokens, you should immediately revoke them and generate new ones.

All API requests must be addressed to api.infinity.health, and made over HTTPS. Calls made over plain HTTP will fail.

Requests that require authentication will return 404 Not Found, instead of 403 Forbidden, in some places. This is to prevent the accidental leakage of private repositories to unauthorized users.

Authenticating with invalid credentials will return 401 Unauthorized.

Encoding

Data is encoded as defined by JSON in RFC 8259. The default encoding for APIs is UTF-8. Certain characters may be handled as surrogate unicode pairs.

HTTP verbs

Request methods are used in accordance with HTTP. Where possible, Infinity API strives to use appropriate HTTP verbs for each action.

Verb	Description
GET	Used for retrieving resources
POST	Used for creating resources
PUT	Used for updating resources
DELETE	Used for removing resources

Responses use standard HTTP codes. Where there are client or server errors, a list of one or more errors in JSON format is returned in the body.

The API may send cache directives where suitable, notably the ETag, Last-Modified and If-Modified-Since headers.

The Accept header must be used by a client used. Requests without an Accept header of application/json may be rejected with a client error of 406 Not Acceptable.

Responses and errors

Infinity API borrows some hints from the JSON:API specification. Responses are JSON objects containing either the data or error key. They never coexist within the same object.

The data key is returned in a successful response. It's either a single object, the value null, or an array of objects. Which can be empty.

For successful responses, Infinity may return, in addition to 200 OK, statuses 201 Created, 202 Accepted, or 204 No Content.

The error key represents client or server errors. It's an Error object with the following keys:

Key	Description	Type
id	Unique machine-readable identifier	String
status	HTTP status code	Integer
title	A human-readable message providing more details about the error	String
detail	Optional object with extra information about the error	null or object

Infinity uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided, e.g., a required parameter was omitted. Codes in the 5xx range indicate an API error.

Errors summary

ID	Status	Title
unauthorized	401	Unauthorized
forbidden	403	Forbidden
not_found	404	Not found
invalid_parameters	422	Invalid parameters
api_error	500	API error