REST API

pgschk edited this page Nov 4, 2013 · 42 revisions
Clone this wiki locally

REST API

The Pasty server offers a REST API that will be stable for each release. API changes will be implemented with a new URL-prefix. This means, that once an API version is marked stable, it won't change. However, the API version may be removed from production, when it is obsolete. There will always be enough time to migrate an app to newer API versions, before an old API version vanishes.

API Server

Host: api.pastyapp.org
HTTPS-Port: 443
HTTP-Port: 80
You are always encouraged to use SSL. However the certificate used is signed with an intermediate ca cert, that not all clients will accept.

Choosing your API version

When querying the API server, you will have to decide which API version you want. While you may always want the latest version, it is important for the stability of your client to make a decision, explicitly requesting a certain API version. If you do not make a decision, the server will, and you may not like it. There are two ways of choosing the API version. Either way is fine, just make an informed decision.

###Prefixing the API endpoint You can prefix the API endpoint with /vX.Y/, X being the major version of the API and Y being the minor version. For example /v2/clipboard/list.json will deliver the users clipboard in API version 2.0 format. Note that for .0 the minor indicator is omitted. /v2.1/server/username will for example result in a API version 2.1 formatted answer.

###Setting Accept-Version The API server accepts an Accept-Version HTTP header in your request, specifying which API version you want. You can set this header either coarsly, like Accept-Version: ~2, which will get you the most recent version of API 2.x, or you can set it explicitly. Note that, unlike with route prefixing, you will need to use full semver syntax: Accept-Version: 2.1.0. This kind of version choosing of course goes best with unprefixed API endpoints (e.g. /server/version instead of /v2/server/version).

###Illegal requests Now what would happen if you where to mix these two methods in an illegal way, let's say we request /v2.1/server/version while setting Accept-Version: ~1?

$ curl -s -H 'accept-version: ~1' api.pastyapp.org/v2.1/server/version

{"code":"InvalidVersion","message":"~1 is not supported by GET /v2.1/server/version"}

As you can see the server will not accept this request, telling you, that your Accept-Version is not supported by this API endpoint. Note that this error message will always come in RestError format, which usually would only be supported by API version 2.1.


API Version 2.1

State: stable, current
API version 2.1. Adds enhanced functionality to API version 2. The current API version that you should use.

See API Version 2.1 Documentation


API Version 2

State: stable, obsolete
API version 2. The previous API version. You should not develope for this version anymore, but still using it is fine.

See API Version 2 Documentation


API Version 1

State: stable, obsolete
API version 1. Initial version, however, full of flaws and with a bad design. Most likely to vanish from production in time.

See API Version 1 Documentation