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 could be provided with every request:

header description
X-API-Key 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 mote information.
401 The X-API-Key header 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.

Resources

You may also enjoy the interactive interface provided for this API by Swagger.

Try it out!

name path methods description
Members
  • /api/v1/members
  • /api/v1/members/_bulk
  • /api/v1/members/{identifier}
  • GET POST
  • POST
  • DELETE GET PATCH