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"
Weavy Docs