Web API
The Weavy backend application exposes a Web API under the /api
path with endpoints for manipulating objects such as Apps, Users, Messages, Files etc.
Introduction
The API is based on the following guiding principles:
- Only available over HTTPS.
- Uses Bearer authentication with token in the Authorization header.
- Utilizes standard HTTP verbs and error codes.
- Parameters should be sent as JSON unless stated otherwise.
- Always returns JSON (properties with
null
values will be omitted from the response). - All dates return in UTC time, using the ISO 8601 format
YYYY-MM-DDTHH:MM:SSZ
.
Authentication
In order to make authorized calls to the API, your application should pass a bearer token in the Authorization
header.
The authentication article explains how to acquire tokens for different scenarios.
Example: In the example below we show how you can call the API endpoint for listing users.
$ curl -H "Authorization: Bearer {token}" https://{weavy-server}/api/users
HTTP verbs
Where possible, the API strives to use appropriate HTTP verbs for actions.
Verb | Description |
---|---|
GET |
Used for retrieving resources. |
POST |
Used for creating resources. |
PATCH |
Used for updating resources with partial JSON data. |
PUT |
Used for replacing resources or collections. |
DELETE |
Used for deleting resources. |
Errors
API calls that result in an error code (HTTP 400 or higher) produces a problem detail response.
Example: HTTP 404 Not Found
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
"title": "Not Found",
"status": 404
}
Summary and detail responses
When you fetch a list of resources, the response includes a subset of the attributes for that resource. This is the "summary" representation of the resource. Some attributes are computationally expensive for the API to provide, and for performance reasons, the summary representation excludes those attributes. To obtain those attributes, fetch the "detailed" representation as mentioned below.
Example: When you get a list of apps, you get the "summary" representation of each app.
GET /api/apps
Example: When you fetch an individual resource, the response typically includes all attributes for that resource. This is the "detailed" representation.
GET /api/apps/{uid}
Parameters
Many API methods take optional parameters. For GET
requests, any parameter not specified as a segment in the path can be passed in the query string:
Example: The uid
parameter ("myapp"
) is passed in the path and the top
parameter (10
) is passed in the query string. See pagination for more information on returning a range of items from the API.
$ curl -H "Authorization: Bearer {token}" https://{weavy-server}/api/apps/myapp/members?top=10
Pagination
Requests that return multiple items is limited to 25 items by default, but you can specify further items (up to 100) with the top
parameter.
To return a specific range of items you can combine that with the skip
parameter.
Example: Return users 6-10 by skipping the first 5 records and then returning the next 5 records.
$ curl -H "Authorization: Bearer {token}" "https://{weavy-server}/api/users?skip=5&top=5"