API

The API responses adheres to json:api standards. All endpoints are available without throttling.

Get public data

Prepend all requests with https://panoptikum.social/jsonapi.

All instances in “relationships” can be found with a link and a minimal set of attributes in “included”. You can basically explore the whole API world of Panoptikum by starting at /categories and following links from there recursively.

The ETag is is response header, containing the MD5 hash of the JSON to be sent. You can make a HEAD request, compare the ETag response header to the last one you have stored and know, that there isn’t anything new, if the ETag has not changed. If there are changes, go on with the GET request and get the full JSON.

Pagination

Podcasts within a category, gigs for a persona and episodes for a podcast are paginated:

• Example request: https://panoptikum.social/jsonapi/personas/1?page[number]=1&page[size]=10
• page[number] … page number; starts counting at 1, defaults to 1
• page[size] … number of items per page, defaults to 10, maximum 1000
• Links contain self, prev, next, last and first link (if appropriate).

Full Text Search

User generation

You can use any user generated in the web interface for full API access, but you can also create users via the API itself.

Login

To be able to post data and receive your own private data, it’s necessary to post a token along side. To get a token, post username and password to recieve a token back, that’s valid for one hour. The token will also be provided in the header token.

Typically, you would call something a login, though it’s only getting you a new token, we provide both routes as endpoints, take the one with the name you prefer. There is no session or cookie connected to that, so there is also no logout.

One user can access the application via the api from different devices simuntaneously. They are not device specific.

Only users with confirmed email address can aquire tokens. Please make sure, that you click the email confirmation link in the email that is sent to you after login via the web interface. There will be an approriate error message telling you to do so, if you request a token and your email is not confirmed yet.

Example: Get a token

If working with tokens is something new for you, an example might help to set the expectations right.

Request:

curl --data "username=janedoe&password=secret" https://panoptikum.social/jsonapi/login

Response:

{"jsonapi":
  {"version":"1.0"},
  "data":{"type":"session-api",
          "id":"6",
          "attributes":{"valid-until":"2017-09-08T16:46:08.393642Z",
                        "valid-for":"1 hour",
                        "token":"SFMyNTY.g3QAAAACdwRk....yNXj3wvSs9a9Ps5wO6yrY",
                        "created-at":"2017-09-08T15:46:08.393630Z"}}}

A note on security

You get the token in a transport encrypted response via https. If you disclose the token, you basically disclose your password. This is the case because the token owner can change the password within the next hour, no matter if you recreated another token. So don’t store it unencrypted.

Post data and get private data

For all these end points it is necessary to provide a valid token. Unless you do so, you will receive appropriate feedback, if the token is invalid, out of date or has not been provided at all.

The token has to be provided as “Authorization: Bearer :token” header, where you exchange the variable :token with the token, that you aquired before as described above.

Why didn’d we choose to support a token provided as a parameter, you might ask? We don’t want to log tokens, which we would have done for get requests.

Requests are done with or for the user identified by the token.

Post, patch and put requests have all params on top level, as we don’t have nested resources available here, see documentation for the idividual requests below. E.g., instead of json:api style

PATCH /pan/personas/42

data: {type: "personas",
       id: "42",
       attributes: {name: "My new name",
                    uri: "https://uri/to/me"}}

you would simply post in a more REST style:

PATCH /pan/personas/42

name: "My new name",
uri: "https://uri/to/me"

Example: Like a podcast

Here is an example how you would like (or unlike, it you liked it before) a podcast.

Request:

curl --data "username=informatom&password=secret" https://panoptikum.social/jsonapi/login

Pick up the token from the response and provide it in the next request as a header.

Request:

curl --data "podcast_id=104" -H "Authorization: Bearer SFMyNTY.g3QAAAACdwRk....yNXj3wvSs9a9Ps5wO6yrY" https://panoptikum.social/jsonapi/pan/likes/toggle

Example: Upload a file

To send a file from the local file system with the parameter upload, a curl request like this can be used:

curl -v -H "Authorization: Bearer :token" -F "upload=@/full/path/to/opml.xml" https://panoptikum.social/jsonapi/pan/opmls

Example: Delete a file

To delete a file via curl, you have to set the request method via the X flag:

curl -v -X "DELETE" -H "Authorization: Bearer :token" http://localhost:4000/jsonapi/pan/opmls/:id