Surfing the Web Concepts

API Days Paris 2018 [http://www.apidays.io/events/paris-2017]

Erik Wilde , API Academy, CA Technologies
January 30, 2018

Creative Commons License [http://creativecommons.org/licenses/by/3.0/]

This work is licensed under a CC
Attribution 3.0 Unported License
[http://creativecommons.org/licenses/by/3.0/]

Contents Erik Wilde : Surfing the Web Concepts

Contents

Erik Wilde : Surfing the Web Concepts

(2) Summary

APIs establish a language between providers and consumers of the provided service. The more this language can be based on well-known vocabularies, the easier it is to design this language for the API provider, and to understand the language for the API consumer. Web Concepts provide a starting point for such a "shared vocabulary", and can be constrained or extended depending on API provider needs. This presentation looks at the general idea of "API as languages", provides a brief overview of the "language components" currently available via http://webconcepts.info/ [http://webconcepts.info/], and presents ways how these concepts can be tailored to address the needs of API managers and developers.



Introduction

Outline (Introduction)

  1. Introduction [4]
  2. APIs are Languages [4]
  3. Languages and Landscapes [4]
  4. Web Concepts [3]
  5. Example: Representations [4]
  6. Conclusions [2]
Introduction Erik Wilde : Surfing the Web Concepts

(4) About Me



Introduction Erik Wilde : Surfing the Web Concepts

(5) @dret on Twitter/GitHub

dret

Introduction Erik Wilde : Surfing the Web Concepts

(6) API Academy [http://www.apiacademy.co/]

API Acacdemy

Introduction Erik Wilde : Surfing the Web Concepts

(7) Microservice Architecture

Microservice Architecture: Aligning Principles, Practices, and Culture

APIs are Languages

Outline (APIs are Languages)

  1. Introduction [4]
  2. APIs are Languages [4]
  3. Languages and Landscapes [4]
  4. Web Concepts [3]
  5. Example: Representations [4]
  6. Conclusions [2]
APIs are Languages Erik Wilde : Surfing the Web Concepts

(9) What is an API?



APIs are Languages Erik Wilde : Surfing the Web Concepts

(10) API Design



APIs are Languages Erik Wilde : Surfing the Web Concepts

(11) Interface Design

Audi RS6 Plus Interior

APIs are Languages Erik Wilde : Surfing the Web Concepts

(12) Continuous Architecture

Model T Speedster

Languages and Landscapes

Outline (Languages and Landscapes)

  1. Introduction [4]
  2. APIs are Languages [4]
  3. Languages and Landscapes [4]
  4. Web Concepts [3]
  5. Example: Representations [4]
  6. Conclusions [2]
Languages and Landscapes Erik Wilde : Surfing the Web Concepts

(14) SOAP: The Dark Age



Languages and Landscapes Erik Wilde : Surfing the Web Concepts

(15) Microservices: Enlightenment



Languages and Landscapes Erik Wilde : Surfing the Web Concepts

(16) The Middle Ground: Guide and Help



Languages and Landscapes Erik Wilde : Surfing the Web Concepts

(17) Language and Design and Culture



Web Concepts

Outline (Web Concepts)

  1. Introduction [4]
  2. APIs are Languages [4]
  3. Languages and Landscapes [4]
  4. Web Concepts [3]
  5. Example: Representations [4]
  6. Conclusions [2]
Web Concepts Erik Wilde : Surfing the Web Concepts

(19) Concepts that matter on the Web



Web Concepts Erik Wilde : Surfing the Web Concepts

(20) Specifications

 "IETF": {
  "id": "http://webconcepts.info/specs/IETF/",
  "name": "Internet Engineering Task Force",
  "short": "IETF",
  "series": [{
   "I-D": {
    "id": "http://webconcepts.info/specs/IETF/I-D/",
    "name": "Internet Draft",
    "short": "I-D",
    "specs": [{
     "amundsen-richardson-foster-alps": {
      "id": "http://webconcepts.info/specs/IETF/I-D/amundsen-richardson-foster-alps",
      "title": "Application-Level Profile Semantics (ALPS)",
      "name": "Internet Draft amundsen-richardson-foster-alps",
      "URI": "urn:ietf:id:amundsen-richardson-foster-alps",
      "URL": "http://tools.ietf.org/html/draft-amundsen-richardson-foster-alps",
      "abstract": "This document describes ALPS, a data format for defining simple descriptions of application-level semantics, similar in complexity to HTML microformats. An ALPS document can be used as a profile to explain the application semantics of a document with an application-agnostic media type (such as HTML, HAL, Collection+JSON, Siren, etc.). This increases the reusability of profile documents across media types.",
      "concepts": [{
       "http://webconcepts.info/concepts/media-type/": "http://webconcepts.info/concepts/media-type/application/alps+json" }, {
       "http://webconcepts.info/concepts/media-type/": "http://webconcepts.info/concepts/media-type/application/alps+xml" }]}},{


Web Concepts Erik Wilde : Surfing the Web Concepts

(21) Concepts

    { "concept" : "http-authentication-scheme",
      "id" : "http:\/\/webconcepts.info\/concepts\/http-authentication-scheme\/",
      "name-singular" : "HTTP Authentication Scheme",
      "name-plural" : "HTTP Authentication Schemes",
      "registry" : "http:\/\/www.iana.org\/assignments\/http-authschemes\/http-authschemes.xhtml#authschemes",
      "values" : 
      [ 
        { "value" : "Basic",
          "concept" : "http:\/\/webconcepts.info\/concepts\/http-authentication-scheme\/",
          "id" : "http:\/\/webconcepts.info\/concepts\/http-authentication-scheme\/Basic",
          "details" : 
          [ 
            { "description" : "The Basic authentication scheme is based on the model that the client needs to authenticate itself with a user-id and a password for each protection space (\"realm\"). The realm value is a free-form string that can only be compared for equality with other realms on that server.",
              "documentation" : "http:\/\/tools.ietf.org\/html\/rfc7617#section-2",
              "specification" : "http:\/\/webconcepts.info\/specs\/IETF\/RFC\/7617",
              "spec-name" : "RFC 7617" } ] },
        


Example: Representations

Outline (Example: Representations)

  1. Introduction [4]
  2. APIs are Languages [4]
  3. Languages and Landscapes [4]
  4. Web Concepts [3]
  5. Example: Representations [4]
  6. Conclusions [2]
Example: Representations Erik Wilde : Surfing the Web Concepts

(23) Resource Representations



Example: Representations Erik Wilde : Surfing the Web Concepts

(24) Reusing Representations



Example: Representations Erik Wilde : Surfing the Web Concepts

(25) Adding Representations



Example: Representations Erik Wilde : Surfing the Web Concepts

(26) Mixing Representations



Conclusions

Outline (Conclusions)

  1. Introduction [4]
  2. APIs are Languages [4]
  3. Languages and Landscapes [4]
  4. Web Concepts [3]
  5. Example: Representations [4]
  6. Conclusions [2]
Conclusions Erik Wilde : Surfing the Web Concepts

(28) But What Now? Help Web Concepts!



Conclusions Erik Wilde : Surfing the Web Concepts

(29) Thanks! Q&A

What's Next?

January 30, 2018 API Days Paris 2018 [http://www.apidays.io/events/paris-2017]