bexio API

Introduction

The bexio API is a REST interface. The API supports the following HTTP verbs:

Verb Description
GET requests a resource from the server.
POST creates a new resource oder or edits an existing one. (partial Update)
PUT edits an existing resource. (full Update)
DELETE deletes a resource.

Quick Start

The bexio API supports the authorization framework OAuth 2.0.

Due to the extensive OAuth 2.0 standard, implementing it is a difficult task. We recommend reading the OAuth-Documentation for a quick start. You may also have a look at our integration sample.

HTTP-Codes

Actions and errors yield different HTTP response codes. Please have a look at the expected response codes in the following list.

Code Description
200 Request OK
201 New resource created
304 The resource has not been changed
400 The request parameters are invalid
401 The bearer token or the provided api key is invalid
403 You do not possess the required rights to access this resource.
404 The resource could not be found / is unknown.
415 The data could not be processed or the accept header is invalid.
422 Could not save the entity
500 An unexpected condition was encountered
503 The server is not available (maintenance work).

HTTP-Headers

You must provide the following headers in each request:

Header Valid values Description
Accept - application/json The format you want to communicate with the api. The format application/xml can be used for read-only requests. But you are strongly encouraed to use the format application/json
Authorization Bearer %access_token% If you use the OAuth 2.0 authorization, you must provide the authorization header.
Signature md5 hash The signature header is only used if you use the api with a public and signature key. You do not have to provide this header if you are using the OAuth 2.0 authorization.
The signature is a checksum which is calculated by the data of the request. The structure of this signature is further explained on the page "signature"

Conditional requests

Most responses return an ETag header. You can track changes on the resource by comparing the ETag headers. Everytime the resource is changed, a new ETag will be generated. You may provide the optional header If-None-Match on your request. If the resource did not change, you will receive the status code 304 Not Modified. You can speed up your requests by using the If-None-Match header.

Example ETag

GET /contact/1

Response

Content-Type: application/javascript
Content-Length: 467
ETag: 66ba7d7c107b12ab64b19ba4846073c3

Example If-None-Match

GET /contact/1
Accept: application/json
Authorization: Bearer 677a1598d208d6c303fa5ca1c774709250e21749
If-None-Match: 66ba7d7c107b12ab64b19ba4846073c3

Response

Status: 304 Not Modified

Tools

We suggest the following tools to test the api: