Skip to main content
Version: 0.0.0

jasima.app API

Under construction

This documentation is a work in progress. Please get in touch with us if you have any questions.

Learn how to use the jasima.app API. Everything that can be done within the portal can also be achieved using our API, documented in this section.

Authentication​

We use OpenID Connect for authentication, and authentication must be performed using your normal user account with the authorisation code flow. You may set the redirect_uri to localhost (any port) to allow the use of desktop applications, command-line tools, or scripts. Once you have retrieved your access token, this should be passed to the API in an "Authorization" header:

Authorization: Bearer <token>

Additionally, you must pass a header containing your organisation identifier. This allows individual users to operate on the resources of multiple organisations without requiring multiple user credentials.

Organisation-Id: 263

Data Format​

The API uses JSON as the default format for both requests and responses, ensuring consistency and simplicity in data handling:

  • For GET requests, the API expects parameters to be passed via query strings.
  • For other HTTP methods (e.g., POST, PUT), the request body (if required) should be formatted as JSON.

There is no need to explicitly specify content encoding in the headers, as the API assumes JSON by default for all applicable requests and responses.

Pagination​

The API supports pagination to manage large datasets efficiently. Use the page and perPage query parameters to control the data returned in your requests. Parameters:

  • page: The page number to retrieve.
  • size: The number of items to include per page.

Example request:

GET https://api.jasima.app/api/v1/widgets?page=1&size=10

Example response:

{
  "items": [
  ],
  "total": 0,
  "page": 1,
  "size": 10,
  "pages": 0
}

Bear in mind the following:

  • The page field in the response indicates the current page being viewed.
  • The total field shows the total number of items available.
  • The pages field indicates the total number of pages, and can be used to determine whether there are additional pages to fetch.

Use this structure to efficiently navigate through large datasets while ensuring optimal performance.

Errors​

TODO

Document the common status codes, and the validation error response format.

Schemas​

Authentication​

Security Scheme Type:

openIdConnect

OpenID Connect URL:

https://id.guardianproject.info/realms/gp/.well-known/openid-configuration