Requests & responses

Geschreven:

Requests

Basis-url

https://rompslomp.nl/api/v1

Acties

De Rompslomp API is RESTful. Resources, zoals facturen en betalingen, hebben een locatie die relatief is aan de basis-url. De HTTP methode die wordt gebruikt bij het request bepaalt de actie die wordt uitgevoerd.

Methode Locatie Actie
GET /{company_id}/{resource_type} Lijst van resources opvragen
GET /{company_id}/{resource_type}/{id} Resource opvragen
POST /{company_id}/{resource_type} Resource aanmaken
PATCH /{company_id}/{resource_type}/{id} Resource bijwerken
DELETE /{company_id}/{resource_type}/{id} Resource verwijderen

Toelichting bij plaatsvervangende aanduidingen:

{company_id}
Het unieke identificatienummer van een bedrijf.
{resource_type}
Het resource-type, zoals facturen (sales_invoices) of contacten (contacts).
{id}
Het unieke identificatienummer van een resource.

Welke acties beschikbaar zijn verschilt per resource-type. Bij API endpoints vind je het complete overzicht van alle resource-typen, acties en opties.

Dataformaat

Request bodies moeten als JSON worden opgemaakt. De 'Content-Type' request header moet zijn 'application/json'.

Voorbeeld-requests

Facturen ophalen

curl --request GET 'https://rompslomp.nl/api/v1/companies/54321/sales_invoices?per_page=1&page=2' \
  --header 'Authorization: Bearer NxtsAs1T6P9TcApiTl4DGcLulrLQDqzIWhdaOBI07gU'

Contact bijwerken

curl --request PATCH 'https://rompslomp.nl/api/v1/companies/654/contacts/321' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer NxtsAs1T6P9TcApiTl4DGcLulrLQDqzIWhdaOBI07gU' \
  --data-raw '{
    "contact": {
      "city": "Utrecht"
    }
  }'

Lees over het bijwerken van subresources op de Subresources pagina.

Responses

Dataformaat

Response bodies zijn altijd als JSON opgemaakt, ongeacht de gebruikte 'Accept' header.

Voorbeeld-response

Betalingen ophalen

HTTP/1.1 200 OK
X-Per-Page: 40
X-Page: 1
X-Total: 1
Content-Type: application/json; charset=utf-8

{
  "payments": [
    {
      "id": 117603,
      "amount": "100.0",
      "description": "Reclamemateriaal",
      "account_id": 513025,
      "paid_at": "2020-03-12T11:53:27.000+01:00"
    }
  ]
}

(Niet-relevante headers zijn weggelaten.)

Foutmeldingen

Wanneer er een fout optreedt krijgt de response de relevante statuscode en bevat de response body een JSON object die de fout beschrijft. Elk foutobject bevat een vast type en een omschrijving of uitleg.

Voorbeeld error-response

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Rompslomp API v1", error="invalid_token", error_description="Het toegangstoken is ongeldig"
Content-Type: application/json; charset=utf-8

{
  "error": {
    "message": "Het toegangstoken is ongeldig",
    "type": "client.authentication.invalid_token"
  }
}

(Niet-relevante headers zijn weggelaten.)

Error-responses

De volgende tabel geeft een overzicht van de mogelijke error-responses.

Status Error-type(s) Informatie
400 client.parameters.invalid_parameter_value
client.parameters.unpermitted_parameters
client.parameters.missing_parameter
client.parameters.malformed_json
401 client.authentication.invalid_token Het toegangstoken bestaat niet (meer).
403 client.authorization.invalid_scope
client.authorization.access_denied
Het toegangstoken geeft niet voldoende toegang, de eigenaar van het API token heeft geen toegang (meer), óf de administratie heeft de API add-on niet geactiveerd.
404 client.not_found.resource
client.not_found.endpoint
422 client.parameters.validation
429 client.rate_limit Meer over request-begrenzing vind je bij de algemene informatie.
500 server Onvoorziene fout in de Rompslomp API. Probeer het later nog eens.