1. Learn
  2. Web API

Learn about the Web API

The Weavy environment 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.
Web API reference

Once you've learned about the Web API you can find all the details about API endpoints in the reference.

Reference

Authentication

Authenticating against the Web API is done using Bearer authentication over HTTPS (SSL). This article documents some best practices when using tokens, and explains how to acquire tokens for different scenarios such as server-to-server and user-to-server.

Best practices

Here are some basic considerations to keep in mind when using tokens:

  • Keep it secret. Keep it safe: A token should be treated like any other credential and revealed only to services that need it.
  • Give tokens an expiration: Technically, once a token is created, it is valid forever—unless it is revoked and/or configured to expire. This could pose potential issues so you should develop a strategy for expiring and/or revoking tokens.
  • Embrace HTTPS: Do not send tokens over HTTP connections as those requests can be intercepted and tokens compromised.
  • Store and reuse: Reduce unnecessary roundtrips that extend your application's attack surface, by storing and re-using tokens. Rather than always creating or requesting new tokens, use the stored tokens during future calls until they expire. How you decide to store your tokens is crucial to defending your application against malicious attacks. Typical solutions include databases and configuration files.

Server-to-server

An API key is used for server-to-server communication and can be generated from the Weavy account. While API keys can be configured to never expire, we strongly recommend that you set an expiration date to prevent potential security issues.

API keys does not associate your request with a user account. Instead, permissions are evaluated in the sudo context which gives your app the powers of a "super user". It is therefore very important that the you store the token securely and never expose it in client side code or similar.

User-to-server

When your application acts on behalf of a user, it performs a user-to-server request. These requests must contain an access token for the user in the Authorization header and associates the request with the authenticated user.

To obtain an access token you make a request from your server to the Weavy environment as described below. The request should be made to the /api/users/{uid}/tokens endpoint. If a matching user is found, the Weavy environment returns an access token. If no matching user is found, the Weavy environment first creates a new user account with the specified uid and then issues an access token.

The uid is a string that uniquely identifies your user (typically your internal user id), but since it cannot contain whitespace and must contain at least one non-digit you might need to customize it. For instance, if a user has the integer id 256 in your system you can create an uid by adding a one letter prefix, e.g. "u256".

The example below shows a request that returns an access token. Since this is a server-to-server request the {token} parameter should be an API key.

$ curl -H "Authorization: Bearer {token}" -X POST https://{weavy-server}/api/users/{uid}/tokens

{
    "access_token": "wyu_IlLQ7qGxU6iRE5pqb6Tle2zBXq4vPu1AgrqQ",
    "expires_in": 3600
}

By default access tokens expire after 3600 seconds (1 hour) but you can optionally specify a custom lifetime with the expires_in parameter. The /api/users/{uid}/tokens endpoint can also be used to sync user profile data from your application to the Weavy environment. You typically want to set at least a name and maybe a profile picture.

Example: Request a token valid for 86400 seconds (24 hours) and set name of user to "John Doe".

$ curl -H "Authorization: Bearer {token}" --json '{"expires_in": 86400, "name": "John Doe"}' https://{weavy-server}/api/users/{uid}/tokens

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