Socie's REST API

This REST API can be used to create, read, update or delete data from the Socie platform. This page provides useful information to get started and an overview of all available resources with their routes. Each route has their own detailed description on how to use it. The base URL for the API is https://api.socie.nl.

Authentication

Socie's REST API supports API Key authentication. The API Key can be created in the settings of your community. There you can also configure for which resources the key can be used. In order to authenticate with HTTP, the following header or query param could be provided with every request:

name	type	description
X-API-Key	header	The API Key for your community.
api_key	query	The API Key for your community.

Rate limiting

Every API Key is allowed to perform 1000 requests per hour. This is measured by saving the date of the initial request and counting all requests in the next hour. If a request is made after 1 hour, the date of the request will be saved and the counter will be set to 1. When an API Key goes over the limit, HTTP status code 429 is returned. The returned HTTP headers of any API request show the current rate limit status:

header	description
X-RateLimit-Limit	The maximum number of requests the API Key is allowed to make per hour.
X-RateLimit-Remaining	The number of requests remaining in the current rate limit window.
X-RateLimit-Reset	The time at which the current rate limit window resets in UTC epoch seconds.

Sorting

Some routes that return a list of data support the ability to sort the response. It is indicated per route which fields can be used for sorting. By default the response is sorted by creation date in ascending order. To sort on the response on another field, you can provide the sort parameter.

Sort by lastName

You can sort members by their last name in descending order. Use a GET request with the following syntax:

Request

  GET https://api.socie.nl/api/v1/members?sort=lastName:desc
  Content-Type: */*
  Accept: application/json
  X-API-Key: ...

If you want to sort the response in ascending order, use :asc instead of :desc.

Sort by multiple fields

It is also possible to sort on multiple fields at once. When 2 values of the first field are equal, the second field is used to determine the order. You can use this by passing the next field separated by a comma. In the example below the last name is sorted descending and the creation date ascending.

Request

  GET https://api.socie.nl/api/v1/members?sort=lastName:desc,created:asc
  Content-Type: */*
  Accept: application/json
  X-API-Key: ...

Pagination

Socie's REST API also supports pagination when retrieving lists of data. This can be useful to limit the amount of data transferred and improves performance. We therefore recommend using this whenever possible.

Set the limit parameter

If you want to receive only 10 results from a route, you can use ?limit=10. When you use this to retrieve members, it will look something like this:

Request

  GET https://api.socie.nl/api/v1/members?limit=10
  Content-Type: */*
  Accept: application/json
  X-API-Key: ...

Response

  HTTP/1.1 200 OK
  Content-Type: application/json

  
    {
      "_links" : {
        "base" : "https://api.socie.nl",
        "next" : "/api/v1/members?skip=10&limit=10",
        "self" : "https://api.socie.nl/api/v1/members"
      },
      "results" : [ { }, { } ],
      "limit" : 10,
      "size" : 10
    }
    
  

In the above response, the value for next shows the URL for the next page of results. Note there's no previous link in the response, meaning there's no results before this page.

GET the next page of results

You can then make a call to return the next page. The skip parameter in the next URL is 10, so the next page of results will show item 10 through 19.

The call will be as follows:

Request

  GET https://api.socie.nl/api/v1/members?skip=10&limit=10
  Content-Type: */*
  Accept: application/json
  X-API-Key: ...

Response

  HTTP/1.1 200 OK
  Content-Type: application/json

  
    {
      "_links" : {
        "base" : "https://api.socie.nl",
        "prev" : "/api/v1/members?skip=0&limit=10",
        "next" : "/api/v1/members?skip=20&limit=10",
        "self" : "https://api.socie.nl/api/v1/members"
      },
      "results" : [ { }, { } ],
      "skip" : 10,
      "limit" : 10,
      "size" : 10
    }
    
  

This time the response contains URLs for both next and prev (previous) pages. When the next URL is missing, you know you've reached the end of the results.

Common response codes

Each route shows for each method which data they expect and which they will respond when the call succeeds. The table below shows some common response codes you can receive from Socie's REST API.

code	condition
200	The GET request was handled successfully. The response provides the requested data.
201	The POST request was handled successfully. The object is created.
204	The PATCH or DELETE request was handled successfully. The object is updated / deleted.
400	The server will not process the request due to something that is perceived to be a client error. Check the provided error for more information.
401	The X-API-Key header or api_key query param is invalid or missing.
403	The API Key is not allowed to perform this method on this route. This could mean the API Key is revoked or does not have the required permission for the resource.
404	No object matched the query.
429	The current API Key made too many requests in the last hour. Check Rate limiting for more information.