Linked Data for Librarians

A Web API is an interface on the server
to expose data & functionality to clients.

• The world of Web APIs and technologies
  is highly heterogeneous.
  • While the human Web reuses many technologies,
    Web APIs suffer from a high rate of reinvention.
• We will discuss about principles,
  consequences, and technologies
  to build and interact with Web APIs.

Why does the Web scale the way it does?
How should we build for the Web?

• Roy Fielding analyzed the Web
  to derive its architectural properties.
• He created the Representational State Transfer (REST) architectural style as a set of
  constraints for distributed hypermedia systems.
• REST has guided protocol decisions
  and can guide Web applications.
  • Being on the Web doesn’t imply following REST.

The REST architectural style consists of
5 types of mandatory constraints.

1. client–server constraints
2. statelessness constraint
3. cache constraints
4. layered system constraints
5. uniform interface constraints

The uniform interface constraints are
unique to the REST architectural style.

REST introduces 4 uniform interface constraints:

1. identification of resources
2. resource manipulation through representations
3. self-descriptive messages
4. hypermedia as the engine of application state

A resource is the main information unit.
An identifier points to at most 1 resource.

• Anything that can be named is a resource.
  • Information resources can be represented in binary code:
    • documents
    • images
    • video
    • software
    • …
  • Non-information resources cannot be represented as bits:
    • people
    • phenomena
    • concepts
    • ideas
    • …
• A valid identifier corresponds to a unique resource.
  • Any resource can have multiple identifiers.
  • One identifier for two resources creates a collision.

A resource is a conceptual relationship:
its value might change over time.

• A resource is a function of time
  that associates a definition with a value.
  • “today’s most read book in Ghent”
    • current value: “top book on 15 February 2016”
    • tomorrow’s value: “the top book on 16 February 2016”
  • “the most read book on 15 February 2016”
    • remains constant, even tomorrow
• This allows late binding.
  • Refer to the concept, whether or not it exists and is final.

Information resources can have
zero or more representations.

• Depending on the needs of a client,
  a resource can be represented differently.
  • “metadata about today’s most read book in Ghent”
    • …in English or Dutch?
    • …in HTML or JSON?
• Representations can also have an identifier.
  • “English HTML document about today’s top book in Ghent”

Each message in a REST interaction
should be self-descriptive.

• Intermediaries can interpret messages.
  • limited number of standardized operations
• All representations are expressed
  in explicit, agreed-upon media types.
  • all semantics are inside of the message

The interaction is driven by
hypermedia controls inside of responses.

• Responses contain hypermedia controls
  such as hyperlinks and forms.
  • indicate what possible steps are
  • explain how to take such steps
• Rather than executing a pre-defined script,
  the client follows the server’s lead.

The Web implements a uniform interface
through URLs, HTTP, and HTML.

The Web supports all 4 uniform interface constraints:

1. identification of resources
2. resource manipulation through representations
3. self-descriptive messages
4. hypermedia as the engine of application state

Web resources are conceptual relations
uniquely identified by HTTP URLs.

• An HTTP URL points to at most one resource.
  • The URL identifies the resource.
  • If it is an in information resource,
    HTTP allows clients to retrieve a representation of it.
• The concept an URL points to shouldn’t change.
  • Tim Berners-Lee calls such identifiers “Cool URIs”.
  • The value and representations might change over time.

Web resources are conceptual relations
uniquely identified by HTTP URLs.

Clients obtain different representations
through HTTP content negotiation.

• If a URL identifies a resource, clients need
  a mechanism to obtain a representation.
• With content negotiation, a client and server agree
  on the best mutually understandable media type.
• The client indicates its preferences,
  the server advertises its choice.

Clients obtain different representations
through HTTP content negotiation.

Well-defined HTTP methods & headers
and media types enable self-description.

• HTTP provides a limited number of methods.
• HTTP provides an extensible set of headers.
• The Content-Type header details the media type.
  • generic:
    • text/html
    • application/json
    • application/xml
    • …
  • specific:
    • application/atom+xml
    • application/rss+xml
    • …

HTML and other hypermedia documents
can contain hypermedia controls.

• In HTML documents, links can be marked up.
  • <em>http://perdu.com/</em>
    • http://perdu.com/ is not a link.
  • <a href="http://perdu.com/">Perdu?</a>
    • Perdu? is a link.
• As a consequence, users almost never
  have to touch the address bar.

The Web is one implementation of REST. Not every website follows the style.

• Many Web APIs labeled “REST” are just HTTP APIs.
  • The overall architecture enables and encourages REST,
    but cannot enforce it—many people misunderstand it.

An urban architect cannot control individual buildings.

A REST API is a collection of resources.
Any regular website is in fact a REST API.

• Most websites follow the REST principles.
  • Usually there is only one representation per resource.
• Some websites invent proprietary interactions.
  • URLs do not correspond to resources.
  • A typical symptom is a broken back button.
• A REST API means having no—additional—API.
  • Your website is the API.
  • All you need are additional representations.

A resource should relate
an URL to a concept.

Resources allow many representations
under a single URL.

Each message should be self-descriptive
and stand on its own.

The interaction should be
driven by hypermedia.

{
  "title": "War and Peace",
  "artist": {
    "id": 5521

  }
}

{
  "title": "War and Peace",
  "artist": {
    "id": "http://example.org/
           artists/5521"
  }
}

Servers offering a hypermedia API
enable the follow your nose principle.

• The term “hypermedia API” is sometimes used
  to indicate APIs that follow all REST principles.
  • The “REST” label is often used incorrectly.
  • Hypermedia is the distinguishing characteristic.
• A client should be able to follow its nose
  around the API from any starting point.
  • This requires a pre-coded understanding of
    the hypermedia content type and its link/form types.

To understand hypermedia’s importance,
imagine using any website without it.

You’d need to read the documentation,
and hard-code it.

Most Web APIs do not follow REST.
They do not focus on the long term.

• REST architectures aim for sustainability,
  offering constants in a changing world.
  • Resources maintain their URL as technologies change.
• “Why design for the long term
  when my API might not be around for long?”
• Even in scenarios where the long term matters,
  REST is not always applied.
  • Both publishers and consumers need to invest more.

Exposing cultural heritage metadata
requires a long-term architectural vision.

• Europeana is a Web portal for
  cultural heritage metadata of Europe.
• It aggregates metadata from 2,000+ institutions.
  • British Library
  • Louvre
  • Ghent University Library
  • …
• Europeana publishes its metadata
  on a website with content negotiation
  and as a separate Web API.

Using the Europeana website
as a human is straightforward.

• You can browse items.
• You can search for items by keyword.
• You can link to items.
  • http://www.europeana.eu/portal/en/record/​9200229/BibliographicResource_3000135601313

Using the Europeana website
as a machine is possible in two ways.

• They can use the regular website
  with content negotiation.
• They can use the dedicated machine API.
  • It is an HTTP API, but not a REST API.

Which one would be easier?

Retrieving an item through the website
as a machine takes one step.

1. Use the same URL of the item, but ask for JSON.

Using the dedicated Europeana API
is quite complicated.

• You have to read the documentation.
  • They mistakenly call the HTTP API a “REST API”.
• You’ll need to get an API key.
• You must follow a specific order of requests.

All of that wasn’t necessary for the website,
even though it contains the exact same information.

Retrieving an item through the API
involves at least 5 steps.

1. Register for an API key.
2. Find the right URL template for the API call.
3. Find out the object ID of your object.
4. Fill out the template to construct the URL.
5. Retrieve a representation using this URL.

The URL you obtain from those steps
is personalized and thus volatile.

http://europeana.eu/api/v2/record/9200229/​BibliographicResource_3000135601313.json?wskey=xxxxxxxxx

• What is this?
• Can I bookmark this?
• Can I share this?

The JSON cannot be shared nor cached,
and you need the documentation.

{
  "apikey": "xxxxxxxxx",
  "action": "--deprecated--",
  "success": true,
  "statsDuration": 110,
  "requestNumber": 999,
  "object": {
    "type": "IMAGE",
    "edmDatasetName": [ "9200229_Ag_EU_TEL_a1112_LibGent" ],
    "title": [ "Belfort, Botermarkt, Gent klokkentoren (1853)" ],
    "about": "/9200229/BibliographicResource_3000135601313",
    "europeanaAggregation": {
      "about": "/aggregation/europeana/9200229/BibliographicResource_3000135601313",
      "aggregatedCHO": "/item/9200229/BibliographicResource_3000135601313",
      "edmLandingPage": "http://europeana.eu/portal/record/9200229/BibliographicResource_3000135601313.html",
      "edmCountry": { "def": [ "belgium" ] },
      "edmLanguage": { "def": [ "mul" ] },
      "edmRights": {
        "def": [ "https://creativecommons.org/licenses/by-sa/4.0/" ]
      },
      "edmPreview": "http://europeanastatic.eu/api/image?uri=http%3A%2F%2Fadore.ugent.be%2FOpenURL%2Fresolve%3Fsvc_id%3Dmedium%26url_ver%3DZ39.88-2004%26rft_id%3Darchive.ugent.be%3A3107D15A-BB55-11E3-8B3D-86C4D43445F2%3A1&size=LARGE&type=IMAGE"
    },
    "proxies": [
      {
        "about": "/proxy/provider/9200229/BibliographicResource_3000135601313",
        "dcDescription": {
          "def": [
            "Stempel op keerzijde afbeelding: Copyright A.C.L.",
            "Handgeschreven notitie op keerzijde afbeelding: 102308 B"
          ]
        },
        "dcFormat": { "en": [ "Printed" ] },
        "dcIdentifier": { "def": [ "002075264" ] },
        "dcRights": {
          "def": [
            "Reproductierecht Universiteitsbibliotheek Gent",
            "CC BY-SA (4.0)"
          ]
        },
        "dcTitle": {
          "def": [ "Belfort, Botermarkt, Gent klokkentoren (1853)" ]
        },
        "dcType": { "en": [ "Serial" ] },
        "dctermsExtent": {
          "def": [ "1 fotografische druk : : zwart/wit." ]
        },
        "dctermsIsPartOf": {
          "def": [ "http://data.theeuropeanlibrary.org/Collection/a1112" ]
        },
        "dctermsIssued": {
          "def": [
            "1875? - 1930?",
            "[eind 19e-begin 20e eeuw]."
          ]
        },
        "dctermsSpatial": {
          "def": [ "België, Vlaanderen, Oost-Vlaanderen, Gent (9000), Gent (9000)" ]
        },
        "proxyIn": [
          "/aggregation/provider/9200229/BibliographicResource_3000135601313"
        ],
        "proxyFor": "/item/9200229/BibliographicResource_3000135601313",
        "edmType": "IMAGE",
        "europeanaProxy": false
      },
      {
        "about": "/proxy/europeana/9200229/BibliographicResource_3000135601313",
        "proxyIn": [
          "/aggregation/europeana/9200229/BibliographicResource_3000135601313"
        ],
        "proxyFor": "/item/9200229/BibliographicResource_3000135601313",
        "edmType": "IMAGE",
        "europeanaProxy": true
      }
    ],
    "aggregations": [
      {
        "about": "/aggregation/provider/9200229/BibliographicResource_3000135601313",
        "edmDataProvider": {
          "def": [ "Ghent University Library" ]
        },
        "edmIsShownBy": "http://adore.ugent.be/OpenURL/app?type=carousel&id=archive.ugent.be:3107D15A-BB55-11E3-8B3D-86C4D43445F2",
        "edmObject": "http://adore.ugent.be/OpenURL/resolve?svc_id=medium&url_ver=Z39.88-2004&rft_id=archive.ugent.be:3107D15A-BB55-11E3-8B3D-86C4D43445F2:1",
        "edmProvider": {
          "en": [ "The European Library" ]
        },
        "edmRights": {
          "def": [ "https://creativecommons.org/licenses/by-sa/4.0/" ]
        },
        "aggregatedCHO": "/item/9200229/BibliographicResource_3000135601313",
        "webResources": [
          {
            "webResourceEdmRights": {
              "def": [ "https://creativecommons.org/licenses/by-sa/4.0/" ]
            },
            "about": "http://adore.ugent.be/OpenURL/app?type=carousel&id=archive.ugent.be:3107D15A-BB55-11E3-8B3D-86C4D43445F2",
            "textAttributionSnippet": "Belfort, Botermarkt, Gent klokkentoren (1853) - http://europeana.eu/portal/record/9200229/BibliographicResource_3000135601313.html. Ghent University Library. CC BY-SA - https://creativecommons.org/licenses/by-sa/4.0/",
            "htmlAttributionSnippet": "<span about='http://data.europeana.eu/item/9200229/BibliographicResource_3000135601313'><a href='http://europeana.eu/portal/record/9200229/BibliographicResource_3000135601313.html'><span property='dc:title'>Belfort, Botermarkt, Gent klokkentoren (1853)</span></a>. Ghent University Library. <a href='https://creativecommons.org/licenses/by-sa/4.0/' rel='xhv:license http://www.europeana.eu/schemas/edm/rights'>CC BY-SA</a><span rel='cc:useGuidelines' resource='http://www.europeana.eu/rights/pd-usage-guide/'>.</span></span>"
          },
          {
            "webResourceEdmRights": {
              "def": [ "https://creativecommons.org/licenses/by-sa/4.0/" ]
            },
            "about": "http://adore.ugent.be/OpenURL/resolve?svc_id=medium&url_ver=Z39.88-2004&rft_id=archive.ugent.be:3107D15A-BB55-11E3-8B3D-86C4D43445F2:1",
            "textAttributionSnippet": "Belfort, Botermarkt, Gent klokkentoren (1853) - http://europeana.eu/portal/record/9200229/BibliographicResource_3000135601313.html. Ghent University Library. CC BY-SA - https://creativecommons.org/licenses/by-sa/4.0/",
            "htmlAttributionSnippet": "<span about='http://data.europeana.eu/item/9200229/BibliographicResource_3000135601313'><a href='http://europeana.eu/portal/record/9200229/BibliographicResource_3000135601313.html'><span property='dc:title'>Belfort, Botermarkt, Gent klokkentoren (1853)</span></a>. Ghent University Library. <a href='https://creativecommons.org/licenses/by-sa/4.0/' rel='xhv:license http://www.europeana.eu/schemas/edm/rights'>CC BY-SA</a><span rel='cc:useGuidelines' resource='http://www.europeana.eu/rights/pd-usage-guide/'>.</span></span>"
          }
        ],
        "edmPreviewNoDistribute": false
      }
    ],
    "providedCHOs": [
      {
        "about": "/item/9200229/BibliographicResource_3000135601313"
      }
    ],
    "europeanaCompleteness": 7,
    "europeanaCollectionName": [ "9200229_Ag_EU_TEL_a1112_LibGent" ],
    "language": [ "mul" ],
    "timestamp_created_epoch": 1442493422613,
    "timestamp_update_epoch": 1455546713777,
    "timestamp_created": "2015-09-17T12:37:02.613Z",
    "timestamp_update": "2016-02-15T14:31:53.777Z"
  }
}

API keys for representations
(not resources) are a fallacy.

• There are many excuses to have API keys.
  • We need to rate limit machine access.
  • We need to track automated access.
  • We need to protect our data.
• Yet API keys do not help with any of these.
  • The HTML version contains the same data without key.
  • We can write a crawler and extract the data from HTML.
• Protect your resources, not your representations.

Europeana’s Web API design choices
have consequences for sustainability.

• You cannot bookmark a URL.
• You cannot share a URL.
• You cannot share nor cache a response.
• You cannot use the API without documentation.
• You cannot use the API in the future.

Europeana’s website design choices
have consequences for sustainability.

• You can bookmark a URL.
• You can share a URL.
• You can share and cache a response.
• You can use the website without documentation.
• You can use the website in the future.

Read more for a deep understanding of
how REST enables sustainability.

• The Fallacy of the Multi-API Culture:
  Conceptual and Practical Benefits of Representational State Transfer (REST)
  • by Ruben Verborgh, Seth van Hooland, et al.
  • with the Cooper-Hewitt National Design Museum
• Published in Journal of Documentation (2015).