Web Fundamentals
Web APIs

Unlike many things from the ’90s,
the Web still works and is in active use.

• The Web has changed.
  • video
  • social media
  • …
• The Web’s users have changed.
  • many more people
  • much more time online
• The Web’s users are no longer only people.
  • crawlers
  • automated clients
  • …

An affordance is a property of an object
that explains and aids its usage.

• The handle affords opening the door.
  • It hints at the opening direction and facilitates opening.
  • However, you can open the door without the handle.
• The handle is an affordance for opening the door.
  • An affordance is not a possibility nor an enabler.
• Even in software, affordances strongly affect usage.
  • Many people use Word, few can use Vim.
  • Affordances are of crucial importance on the Web.

A Web API is a server-side HTTP interface
exposing data and functionality to clients.

• If well designed, a Web API provides the affordances
  for humans and/or machines to interact with it.
• 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.

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.
• Representational State Transfer (REST)
  is an architectural style for building
  distributed hypermedia systems.
• REST has guided protocol decisions
  and can guide Web application design.
  • 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

REST architectures inherit
the client–server constraints.

• The server listens for requests,
  clients send requests via a connector.
  • typical for network-based applications
  • alternatives:
    • peer-to-peer
    • …
• This realizes a separation of concerns.
  • separating user interface from data storage
    • increases scalability by simplifying the server
    • improves portability of the interface across platforms
    • enables independent evolution of client and server

REST architectures constrain
communication to be stateless.

• Each client request must contain all information
  necessary for the server to understand it.
  • The server does not remember the client.
  • The server does not remember previous requests.
• Stateless requests can be interpreted
  independently of each other.
  • stateful:
    1. “show laptops”
    2. “show page 2”
  • stateless:
    1. “show laptops”
    2. “show page 2 of laptops”

Statelessness applies to application state.
Servers still maintain resource state.

• Application state captures the position of a client
  in the interaction, and differs per client.
  • This client is currently looking at page 2 of laptops.
• Resource state captures properties of data entities
  on the server, and are the same for all clients.
  • There are currently 230 laptop models for sale.

This blog post and this book elaborate on the difference.

Statelessness improves visibility,
reliability, and scalability.

visibility

Intermediaries understand each request
without having to know any others.

reliability

Recovery from partial failures is easier
because no request history is needed.

scalability

No data must be kept between requests.

Each request can be handled by a different,
independent server.

Statelessness has increased bandwidth and
reduced server-side control as trade-offs.

bandwidth

Requests might need to repeat information
that was sent previously but not kept.

control

Clients become responsible to transition
consistently from one state into another.

They cannot necessarily be trusted
to make correct and allowed transitions.

The server does not know any client’s previous state.
Clients might jump to unpermitted states by “guessing”.

The REST architectural style
imposes cache constraints.

• A server response indicates explicitly
  whether or not it is cacheable.
  • Cacheable responses may be reused later on
    by clients and/or intermediaries.
• Caching improves network efficiency, scalability,
  and user-perceived performance.
  • The server needs to perform less work.
• Reliability can be reduced if cached data is stale.

The layered system constraints
allow for flexible hierarchical layers.

• Intermediaries can be inserted transparently,
  shielding off complexity and inner details.
  • proxies
  • caches
  • load balancers
  • firewalls
  • …
• Layering increases flexibility
  but can introduce overhead and latency.

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 unit of information.
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 (related) 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 played song in Ghent”
    • current value: “the top song on 15 February 2016”
    • tomorrow’s value: “the top song on 16 February 2016”
  • “the most played song in Ghent 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 and capabilities of a client,
  a resource can be represented differently.
  • “metadata about today’s most played song in Ghent”
    • …in English or Dutch?
    • …in HTML or JSON?
• Representations can also have an identifier.
  • “English HTML document about today’s top song in Ghent”
  • The notion of resource/representation is relative:
    representations become resources when identified.

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

1. Intermediaries can interpret messages.
   1. statelessness and explicit cacheability
   2. limited number of standardized operations
2. Response (and request) bodies are expressed
   in explicit, agreed-upon media types.
   • well-defined syntax and semantics
   • all semantics are inside of the message
     • or the message makes clear where to find them

The interaction is driven by
hypermedia controls inside of responses.

• Responses contain hypermedia controls
  such as hyperlinks and forms.
  • They afford the next steps a client can take.
    1. indicate what possible steps are
    2. explain how to take such steps
• Rather than executing a pre-defined script,
  the client follows the server’s lead.
  • With Remote Procedure Calling, clients instead must know
    the details of the interface and all steps in advance.

Hypermedia defines REST interactions,
minimizing the client–server contract.

• Client and server can evolve independently.
  • From one resource, the client discovers the interface.
  • The client does not bind to concrete identifiers,
    but needs to know the semantics of links and forms.
• The server must afford the actions clients need.
  • How can the server know what the client wants to do?
  • How can anybody know all actions in an open environment?

The Web is one implementation of REST—
and not every website follows the style.

• REST APIs are often HTTP APIs,
  but other platforms can implement the style.
  • The Constrained Application Protocol (CoAP)
    is used by devices on the Internet of Things.
• Many Web APIs labeled “REST” are just HTTP APIs.
  • The overall architecture enables and encourages REST,
    but cannot enforce it (and many people misunderstand it).

An urban architect does not control individual buildings.

How does the Web implement REST using
its core technologies URL, HTTP & HTML?

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

Obviously, the Web consists
of clients and servers.

• Clients make HTTP requests.
• Servers listen and respond to HTTP requests.
• The “client” and “server” labels are roles,
  and relative to the interaction.

The HTTP protocol is designed
in a stateless way.

• Servers don’t remember clients between requests.
  • An IP address is insufficient to identify a client due to NAT.
• Each HTTP request must contain all headers,
  even those that remain the same.
  • Host
  • Accept
  • User-Agent
  • …
• The client–server relation only exists
  during the request and processing of the response.
  • Cookies can establish a session—and thus server-side state.

HTTP realizes caching with intermediaries
and explicit caching headers.

• HTTP responses explicitly indicate cacheability.
  • Cache-Control: max-age=3600
  • ETag: UniqueHash456
• HTTP method semantics define caching influences.
  • GET does not change a resource.
  • POST can change a resource.

HTTP allows transparent insertion
of layers of proxies.

• Reverse proxies act as a gateway
  to application servers.
• There is no stateful client–server connection,
  so intermediaries can transparently answer.
• HTTP can wrap legacy systems.

The uniform interface is implemented
by a combination of URL, HTTP, and HTML.

The Web supports all 4 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 information resource,
    HTTP allows clients to retrieve a representation of it.
• The concept pointed to by a URL shouldn’t change.
  • Tim Berners-Lee calls such identifiers “Cool URIs”.
• The value and representations retrieved
  when looking up a URL 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 with Accept,
  the server advertises its choice with Content-Type.
  • Accept: application/json,text/html;q=0.6
  • Maybe the server likes its HTML better, or has no JSON.

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.
  • Intermediaries can know the semantics of all methods
    (which would be hard if a server could choose its own).
• HTTP provides an extensible set of headers.
  • Intermediaries forward headers they do not understand.
• 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>https://perdu.com/</em>
    • https://perdu.com/ is not a link.
  • <a href="https://perdu.com/">Perdu?</a>
    • Perdu? is, because the HTML media type defines
      the semantics of this element as a hyperlink.
• As a consequence, users almost never
  have to touch the address bar.
  • If they do, the action is not afforded by hypermedia.

Other media types can also have links,
if an interpretation is specified.

• A regular JSON document cannot have hyperlinks.
  • { "url": "https://perdu.com/" } is not a link.
  • The application/json media type
    does not specify an interpretation for links.
• Specific JSON subtypes can have hyperlinks.
  • The application/hal+json media type
    specifies an interpretation for links.
  • This interpretation is only allowed if the server
    replies with Content-Type: application/hal+json.

When I say hypertext,
I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects actions.

Roy Fielding

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. (In theory—practice differs.)
  • All you need are additional representations.

A resource should relate
a URL to a concept.

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

A resource can have many representations
exposed through a single URL.

• Can I bookmark this?
• Can I share this?

Each message should
be self-descriptive.

HTTP/1.1 5027 Incomplete
Custom-Server-Id: song.1.2
Content-Type:
  application/json

HTTP/1.1 200 OK
Server: Song-Server 1.2
Content-Type:
  application/vnd.acme.songs
Cache-Control: max-age=3600

• What is this?
• Can I cache this?

The interaction should be
driven by hypermedia.

{
  "title": "Baba O’Riley",
  "artist": {
    "id": 5521

  }
}

{
  "title": "Baba O’Riley",
  "artist": {
    "id": "https://example.org/
           artists/5521"
  }
}

• Can I act upon this?

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.

https://google.com/

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

There exists a large number of Web APIs,
growing at an increasing rate.

number of Web APIs
indexed in ProgrammableWeb

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.
  • https://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.

curl -H "Accept: application/json" \
https://www.europeana.eu/portal/en/record/9200229/BibliographicResource_3000135601313

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 using the dedicated 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.
   • non-trivial, because the API assumes you always search first
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.

https://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": "https://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": "https://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": "https://adore.ugent.be/OpenURL/app?type=carousel&id=archive.ugent.be:3107D15A-BB55-11E3-8B3D-86C4D43445F2",
        "edmObject": "https://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": "https://adore.ugent.be/OpenURL/app?type=carousel&id=archive.ugent.be:3107D15A-BB55-11E3-8B3D-86C4D43445F2",
            "textAttributionSnippet": "Belfort, Botermarkt, Gent klokkentoren (1853) - https://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='https://data.europeana.eu/item/9200229/BibliographicResource_3000135601313'><a href='https://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 https://www.europeana.eu/schemas/edm/rights'>CC BY-SA</a><span rel='cc:useGuidelines' resource='https://www.europeana.eu/rights/pd-usage-guide/'>.</span></span>"
          },
          {
            "webResourceEdmRights": {
              "def": [ "https://creativecommons.org/licenses/by-sa/4.0/" ]
            },
            "about": "https://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) - https://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='https://data.europeana.eu/item/9200229/BibliographicResource_3000135601313'><a href='https://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 https://www.europeana.eu/schemas/edm/rights'>CC BY-SA</a><span rel='cc:useGuidelines' resource='https://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.

Engineer for serendipity.

Roy Fielding

Web APIs started out as Web services.
The difference is not well-defined.

• Typically, the term “Web services” is used to
  label older, XML-based interfaces on top of HTTP.
• The term “Web APIs” is more fashionable
  for interfaces that use HTTP and JSON.
• Neither of these terms indicate whether
  the REST architectural style was (not) followed.
  • Actual REST APIs are still rare on the Web.

Web services with Remote Procedure Calling
have surprisingly few to do with the Web.

• The client sends a structured request.
  • <request method="getSongDetails" id="22896"/>
• The server replies with a structured response.
  • <response status="success"/>
• There’s nothing intrinsically “Web” about this.
  • The Web acts as a convenient tunnel.
  • (Which firewall would block TCP port 80?)

The Simple Object Access Protocol (SOAP)
transfers XML messages on top of HTTP.

A SOAP message consists of 3 main XML elements.

envelope

root with (optional) header and body

header

modular extension mechanism

body

details of a method invocation

The client sends such an XML document with HTTP POST
to a single specific URL that identifies the service.

This SOAP request calls a method
with one input parameter.

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
  <env:Header>
  </env:Header>
  <env:Body>
    <s:getSongDetails xmlns:m="http://example.org/song-service">
      <s:id>22896</s:id>
    </s:getSongDetails>
  </env:Body>
</env:Envelope>

This SOAP response contains
one output parameter.

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
  <env:Header>
  </env:Header>
  <env:Body>
    <s:songDetails xmlns:m="http://example.org/song-service">
      <s:title>Baba O’Riley</s:title>
      <s:artistId>5521</s:artistId>
    </s:songDetails>
  </env:Body>
</env:Envelope>

SOAP provides language-independent
programming over a network.

• SOAP enables fast cross-language development.
  • notion of networking (and HTTP) is hidden
  • much tooling available
• SOAP does not inherit the Web’s benefits.

  no caching

  all requests use POST

  no visibility

  intermediaries can’t understand requests

  no evolvability

  the contract is hard-coded

• SOAP even works without the Web through e-mail.

Web API descriptions capture machine-interpretable details about an API.

There exist 3 broad uses for descriptions.

in-band

resource and hypermedia control details

interface

structural properties

functional

effect and/or purpose characterization

Description formats support one or more of them.

The Web Services Description Language
(WSDL) describes SOAP service structure.

• A WSDL description is an XML document
  that lists a service’s methods and parameters.
  • just structure, no semantics
• A WSDL description and SOAP wrapper can be
  generated automatically from program code.
• Code to interact with the described SOAP service
  can be generated from the WSDL.
  • hard-coded—change requires recompilation/recoding

OWL-S (Semantic Markup for Web Services)
enriches WSDL with functional aspects.

• An OWL-S description captures the semantics
  of a single SOAP operation using RDF.
• An OWL-S description consist of three parts.

  profile

  high-level functionality for discovery

  grounding

  connection to SOAP parameters

  model

  in-depth functional relations and constraints

• OWL-S is very powerful for RPC, but remains unused.

The Web Application Description Language
(WADL) is the WSDL of non-SOAP Web APIs.

• WADL descriptions detail structural properties.
  • support for XML and JSON
• A WADL description is an XML document
  that details HTTP methods and parameters,
  as well as representation structure.
• WADL enables automated code generation.
  • also hard-coded

Most recent Web API description formats
focus purely on developer support.

• An OpenAPI (formerly Swagger) specification
  documents a Web API’s methods in JSON.
  • documentation for developers (example)
  • automatic client code generation
• API Blueprint focuses on data modeling first.
• Most formats are not fundamentally different.
  • They are tools. Pick the one you like most.

Structural descriptions boost development
but don’t fundamentally change Web APIs.

• They encourage uncontrolled growth
  but hamper a sustainable Web API ecosystem.
  • Everybody builds blindly, nobody reuses.
• They promote tight coupling.
  • Hard-code against a description.
  • If code can be generated anyway… is it necessary?
• In essence, they have little to do with the Web.
  • Do you need to read a website’s contract first?

Hypermedia-based formats place
description inside of the message.

• JSON itself does not support links or forms.
  • Representations of type application/json
    cannot fulfill the hypermedia constraint.
• The Hypertext Application Language (HAL)
  defines links on top of JSON.
  • Representations have type application/hal+json.
  • They contain a _links key with named links.

Hydra is an RDF vocabulary to describe
hypermedia controls and API structure.

• Hydra contains hypermedia building blocks
  to enhance representations with links and forms.
  • Hydra basically offers the <form> of RDF.
  • RDF has several serializations, including JSON and XML.
• In addition to the structure of a REST Web API,
  Hydra can also describe the semantics of resources.
  • Clients can figure out the effect of a hypermedia control.

What the customer
thought they needed

How the project leader
understood it

How the programmer
wrote it

How the customer
was billed

What the customer
really needed

What does the customer
really need?

If a customer wants to make their website accessible
for automated clients, what do you propose?

If they ask for a Web API, what do you propose?

• An additional Web API?
• Additional representations for their website?

And—most importantly—what do you bill them for? 😉