Application Programming Interface

Madek - Medienarchiv der Künste

2014-04-02

Dr. Thomas Schank, ZHdK

Recorded talk (medienarchiv.zhdk.ch)

drtom.ch/talks/2014/04/madek-api

→ next slide / uncover

← previous slide / cover

This presentation uses HTML5 and contains videos. It is known to work well with recent versions of Chrome.

HTTP and APIs

HTTP and APIs

Traditional programming: invoking functions

get(type: 'media_entry',name: 'xy_diplomarbeit_2014')

Context: call history, objects in scope

HTTP: placing and retrieving resources

GET /media_entries/xy_diplomarbeit_2014

No context!

Representational state transfer protocol (REST)

HTTP and APIs

API abusing HTTP

POST /?action=get&type=media_entry&name=xy_diplomarbeit_2014

instead of

GET /media_entries/xy_diplomarbeit_2014

Verbs: PUT, GET, DELETE, ...

Only GET is used in the Madek API (for now)

HTTP and APIs

HATEOAS - Hypermedia as the Engine of Application State

e.g. use links to relate resources

Example

{ owner_id: 15 }

vs

{ owner: 'http://medienarchiv.zhdk.ch/api/users/15' }

HTTP and APIs

HAL - JSON Hypertext Application Language

HAL Specification

Defines structure of JSON-Response

HTTP and APIs - HAL Response Example

{
  "_links": {
      "madek:": {
        "href": "/api"
    }
    , "self": {
        "href": "/api"
    }
    , "madek:media_resources": {
        "href": "/api/media_resources"
    }
    , "curies": [
        {
          "name": "madek"
        , "href": "/public/api_docs/{rel}"
        , "templated": true
      }
    ]
  }
  , "welcome_message": "Welcome to the MAdeK API!"
}

HTTP and APIs - HAL Benefit: Madek API Browser

The Madek API

1. Entry Point and Content Type

Madek API - Entry point /api

Madek API - Entry point /api

Content-Type

application/hal+json
application/json

Except

Remark: There is (almost everywhere) only one suitable content-type for a given resource in the Madek API. In those cases Madek will respond with that one no matter what the accept header says.

This can change at any time in the future.

API clients should use the proper accept-header!

The Madek API

2. Authentication

Madek API - Authentication

Madek API - Application and Authentication

Authentication

Authentication

HTTP Basic

API clients must authenticate to access the API.

  • Registered application

  • Secret

Authentication and Entities

Madek API - Authentication Header

The Madek API

3. Documentation

Documentation /public/api_docs

Documentation

refercence

not necessarily the best way get acquainted with the API

…

The Madek API

4. The Madek API Browser

API Browser /api-browser/browser.html

The Madek API

6. Filtering and Query-Parameters

Filtering and Query-Parameters

Filtering and Query-Parameters

Filtering → Query Parameters

Limited possibilities for now

Will become involved (arrays, nested structures)

Documentation (& Query-Builder?)

The Madek API

7. Authorization I - Viewing

Authorization for Viewing a MediaEntry

Authorization and Entities

The Madek API

8. Downloading - Authorization II

Downloading a MediaEntry

Downloading and the Hypermedia Approach

But wait, Hypermedia

should it not be like

GET /api/media_entries/x accept: application/pdf

instead of

GET /api/media_entries/x/content_stream accept: application/pdf

Certainly! However, content negotiation with browsers, ….

Might change …

API clients should must send proper accept headers!

Downloading and Browsers

But wait, how is this supposed to work:

Concept:

  • forwarding authorization and authentication
  • expiration
  • cryptographically hashed signature

The Madek API

9. MediaResources and Redirects

Redirects

MediaResource-Types and Custom-URLs

  • GET /api/media_resources/madek-entities

  • 302 → http://madek/api/media_resources/6e689070-a514-48a5-bbc3-d83babc66d72

  • GET /api/media_resources/6e689070-a514-48a5-bbc3-d83babc66d72

  • 302 → http://madek/api/media_entries/6e689070-a514-48a5-bbc3-d83babc66d72

  • GET /api/media_entries/6e689070-a514-48a5-bbc3-d83babc66d72

API-Clients should handle redirects!

The Madek API

10. Todo

TODO

  • documentation and specification for existing features

  • forwarding auth for download

  • /api/media-resources/ more filters and parameters

  • /api/media-sets/ and /api/filter-sets/

  • meta-data all

THE END

non persistent data, only within ZHdK net

soon:

links to the old api documentation right now!