Web APIs

Web APIs

What are Web APIs?

Web APIs are

• Application Programming Interfaces.

  • Interfaces to information and functionality provided by systems.
    • The Thoth API provides access to the information managed by Thoth (courses, classes, student groups, ...)
    • The GitHub API provices access to GitHub information and functionality such as creating repos and managing their access control policy.
  • Used by other applications.

• Using elements of the Web architecture.

  • Using URIs as the main identification mechanism.
  • Using HTTP as an application level protocol.
    • And just not as a transport protocol.
    • Examples of application level characteristics.
      • self-contained messages and an uniform interface with well defined semantics.
      • Rich set of status codes
      • Caching.
      • Optimistic concurrency.
      • Security
    • As a contrast, SOAP (initially from "Simple Object Access Protocol") uses HTTP and URIs, however
      • SOAP is used only as a transport protocol for XML messages - always use POST, no HTTP caching, no HTTP content negotiation.
      • Operation identification requires additional information from HTTP headers or SOAP message headers.

Not exactly the same as classic APIs

Web APIs are very different from "classical" APIs provided by JAR (Java Archive) or a DLL (Dynamic Link Library)

• The former are examples of in-process APIs, i.e., the API client and the API provider live in the same process.
  • No communication failures on the API usage (it's "just" parameters on the stack and changing the PC/IP).
    • Namely no transient communication failures.
  • No intermediaries (proxies or gateways).
  • Simpler versioning
    • Provider can have multiple published JARs, with different version names.
    • Each consumer chooses and "freezes" the desired version.
      • Publishing a new version does not impact consumers using previous versions.
• On Web APIs
  • Access failure does happen.
    • Network
      • Access point issues (e.g. WiFi, 4G).
      • DNS resolution.
    • Intermediaries.
    • Software deploys.
  • Access latency may be significant.
  • Versioning is different - having multiple available versions is costly.
    • By being "out-of-proc", replacing a previous version with a new version impacts all consumers using the last version.

Motivation

Motivation for Web APIs

• Multi-platform support ("4 screens": desktop/laptop, smart phone, tablet, TV)
  • And it all started with the iPhone and mobile native applications in 2007.
  • Instead of providing a "site" that returns HTML representations, there was a need to provide representations used by other applications (e.g. the native mobile applications).
• Automation
  • How to create 40 GitHub repositories and define their access control policy?
  • How to create, start and close 100 VMs to run a load test?
  • Examples: GitHub API, Google Cloud Platform.
  • Example: in some ISEL courses, we use both the Thoth and GitHub APIs to automate the provision of private repositories for all student groups.
• API as the product
  • Example: Twilio - APIs for programmable telecommunication services (e.g. SMS, voice).

Not Web APIs are equal

Not all Web API are equal

• Namely from an evolution and versioning viewpoint.
• On one end of the spectrum we have Web APIs with
  • Only one provider.
  • Only one consumer.
  • Controlled by the API provider.
  • Allowing fast and synchronous deployments of both provider and consumer.
  • Short lifetime spans (e.g. months).
• On the other end of the spectrum we have Web APIs with
  • Multiple providers (yes, multiple providers).
    • See The Enterprise Media Distribution Platform At The End Of This Book for an excellent example of this.
  • Multiple consumers.
  • Consumers and providers are not managed by the same entities.
  • Impossibility of having coordinated changes on providers and consumers.
  • Long lifetime spans (e.g. decades)
    • "REST is software design on the scale of decades: every detail is intended to promote software longevity and independent evolution. Many of the constraints are directly opposed to short-term efficiency." in http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
• Most of the Web APIs that we design fit somewhere in the middle