Uniform Interface

The deck during my presentation at Hive Talks Prague https://www.meetup.com/apiaryio/events/240962821/

Transcript

1. GOOD
   API
   THE QUEST FOR THE
   UNIFORM INTERFACE
   Zdenek Nemec
   GOOD
   API
   @zdne
   

   View Slide

2. GOOD
   API
   Zdenek Nemec
   API Consulting
   http://goodapi.co
   GOOD
   API
   @zdne
   zdne1
   

   View Slide

3. GOOD
   API
   GOOD API CONSULTING
   adidas API Guidelines
   https://adidas-group.gitbooks.io/api-guidelines
   

   View Slide

4. GOOD
   API
   UNIFORM INTERFACE
   What is Uniform Interface?
   

   View Slide

5. GOOD
   API
   ENGINEERING PRINCIPLE OF GENERALITY
   

   View Slide

6. GOOD
   API
   THE UNIFORM INTERFACE REFERS TO A STANDARD WAY
   TO DO SOMETHING REGARDLESS OF WHAT THE SPECIFIC
   ACTIVITY IS
   

   View Slide

7. GOOD
   API
   UNIFORM INTERFACE
   1957 2017
   

   View Slide

8. GOOD
   API
   UNIFORM INTERFACE
   

   View Slide

9. GOOD
   API
   TERM COINED BY ROY T. FIELDING IN 2000
   

   View Slide

10. GOOD
    API
    SOFTWARE ENGINEERING PRINCIPLE OF GENERALITY
    APPLIED TO INTERFACE COMPONENT OF A
    COMPONENT IN DISTRIBUTED SYSTEM
    

    View Slide

11. GOOD
    API
    A CONSISTENT, PREDICTABLE WAY TO QUERY DATA
    AND EXERCISE ACTIONS REGARDLESS OF THE
    APPLICATION DOMAIN
    

    View Slide

12. GOOD
    API
    MANIFESTS AS ARCHITECTURAL STYLE CONSTRAINT
    TO ACHIEVE SOME DISTRIBUTED SYSTEM PROPERTIES
    

    View Slide

13. GOOD
    API
    WHY WE WANT UI
    System properties when we apply the UI constraint(s)
    

    View Slide

14. GOOD
    API
    THE BENEFITS OF UI
    

    View Slide

15. GOOD
    API
    SIMPLIFIED ARCHITECTURE
    

    View Slide

16. GOOD
    API
    IMPROVED VISIBILITY OF INTERACTIONS
    

    View Slide

17. GOOD
    API
    DECOUPLED COMPONENTS
    Enable parts to evolve independently
    Abstraction
    Layer
    Comp-A Comp-B
    no welding of
    components
    

    View Slide

18. GOOD
    API
    IMPROVED INTEROPERABILITY
    Reduces the cost of integration
    Two different drivers can drive any car
    

    View Slide

19. GOOD
    API
    REUSABLE CLIENT COMPONENTS
    Reduces development costs and time to market
    

    View Slide

20. GOOD
    API
    NO CLIENT REUSE
    New API 㱺 New client, albeit the API is within the same domain
    Smart Pallet Vendor A Smart Pallet Vendor B
    

    View Slide

21. GOOD
    API
    ENABLES AUTONOMOUS
    SERVICE DISCOVERY
    

    View Slide

22. GOOD
    API
    AUTONOMOUS SERVICE DISCOVERY
    “Get me a service that knows weather in Paris.”
    “Get me a service that can fulfill the parcel logistics of 6 pallets from
    Prague to Paris.”
    “Get me a service that can play every movies by the director of movie
    Avatar.”
    

    View Slide

23. GOOD
    API
    ENABLES FOR GENERAL AI
    

    View Slide

24. GOOD
    API
    UNIVERSE OF CAPABILITIES
    http://viv.ai
    

    View Slide

25. GOOD
    API
    THIS IS WHAT AMAZON ALEXA SKILLS, GOOGLE
    HOME SKILLS & VIV ARE DOING
    BUILD A DATABASE OF KNOWLEDGE AND SERVICES
    WITH UNIFORM INTERFACE…
    

    View Slide

26. GOOD
    API
    THE TRADEOFF OF UI
    

    View Slide

27. GOOD
    API
    DEGRADED EFFICIENCY
    UI
    Transformation
    Comp-A Comp-B
    Transformation
    

    View Slide

28. GOOD
    API
    UNLESS YOU ARE REALLY COUNTING BITS,
    WATTS OR MILLISECONDS THE UI’S BENEFITS
    OUTWEIGHS THE TRADEOFF
    

    View Slide

29. GOOD
    API
    THE QUEST SO FAR
    

    View Slide

30. GOOD
    API
    HOW TO ACHIEVE CONSISTENT INTERFACE
    • SOAP (Tunneling architectural style)
    • REST (Hypermedia architectural style)
    • Query Languages (Tunneling architectural styles)
    • Proprietary function libraries (RPC architectural style)
    • Domain-specific standards (on top of a respective style)
    

    View Slide

31. GOOD
    API
    SOAP
    

    View Slide

32. GOOD
    API
    SOAP
    • Uniform Interface is not part of SOAP
    • Added on the application level of service qualities
    • Security: WS-Security/SecureConversation/Trust
    • Transactions: WS-AtomicTransaction and WS-BusinessActivity
    

    View Slide

33. GOOD
    API
    REST
    

    View Slide

34. GOOD
    API
    REST ARCHITECTURAL STYLE
    

    View Slide

35. GOOD
    API
    REST UI CONSTRAINTS
    • Identification of Resources
    • Manipulation Through Representations
    • Self Descriptive Messages
    • HATEOAS
    

    View Slide

36. GOOD
    API
    

    View Slide

37. GOOD
    API
    HATEOAS
    1. All application state is kept on the client side. Changes
    to application state are the client’s responsibility
    2. The client can only change its application state by
    making an HTTP request and processing the response.
    3. How does the client know which requests it can make
    next? By looking at the hypermedia controls in the
    representations it’s received so far.
    4. Therefore, hypermedia controls are the driving force
    behind changes in application state.
    Credit: RESTful
    Web APIs by
    Richardson &
    Amundsen
    

    View Slide

38. GOOD
    API
    RESTFUL WEB APIS
    RESTful Web APIs by Leonard Richardson & Mike Amundsen
    

    View Slide

39. GOOD
    API
    REST ARCHITECTURAL STYLE
    • Great in theory
    • In reality very few follows the UI constraints, making the
    interfaces incompatible
    • Workarounds possible via explicit standards & governance
    e.g. Oracle+Apiary API Style Guide
    

    View Slide

40. GOOD
    API
    FUNCTION LIBRARIES
    

    View Slide

41. GOOD
    API
    FUNCTION LIBRARIES
    StdLib Algorithmia
    FaaS with Uniform Function Interface
    

    View Slide

42. GOOD
    API
    FUNCTION LIBRARIES
    FaaS with Uniform Function Interface
    

    View Slide

43. GOOD
    API
    QUERY LANGUAGES
    

    View Slide

44. GOOD
    API
    SQL IS THE UNIFORM INTERFACE TO RETRIEVE
    AND MANIPULATE DATA REGARDLESS OF
    WHAT THE DATA ARE
    

    View Slide

45. GOOD
    API
    QUERY LANGUAGES
    GraphQL
    Graql SPARQL
    Query language as the uniform interface
    

    View Slide

46. GOOD
    API
    GraphQL
    

    View Slide

47. GOOD
    API
    BENEFITS
    

    View Slide

48. GOOD
    API
    A CONSISTENT WAY TO QUERY DATA AND EXERCISE
    AFFORDANCES (MUTATIONS)
    

    View Slide

49. GOOD
    API
    FOUNDATION FOR REUSABLE CLIENT
    Relay, Apollo, Loki
    

    View Slide

50. GOOD
    API
    DATA IDENTIFIERS ARE MORE HYPERMEDIA THAN
    URI*
    “URIs” of GraphQL are opaque:
    ID or “path” + ID (Relay route)
    * true for HTTP/LCODC$SS APIs
    

    View Slide

51. GOOD
    API
    SCHEMA (DESIGN) FIRST
    

    View Slide

52. GOOD
    API
    DATA & AFFORDANCES INTROSPECTION AT RUNTIME
    

    View Slide

53. GOOD
    API
    NO VERSIONING
    “GraphQL takes a strong opinion on avoiding versioning by
    providing the tools for the continuous evolution of a GraphQL
    schema.”
    http://graphql.org/learn/best-practices/
    

    View Slide

54. GOOD
    API
    MYTH: OVERFETCHING
    If you are worried about over-fetching you
    are probably using wrong protocol.
    GraphQL
    

    View Slide

55. GOOD
    API
    TRADEOFFS
    

    View Slide

56. GOOD
    API
    ONLY JSON REPRESENTATION
    

    View Slide

57. GOOD
    API
    MISSING SOME OF THE REST
    SYSTEM QUALITIES
    COD & $ which translates to the loss of extensibility
    and cache-ability
    

    View Slide

58. GOOD
    API
    NO AUTH STANDARD
    

    View Slide

59. GOOD
    API
    TIED TO UI DATA STRUCTURE
    

    View Slide

60. GOOD
    API
    NO STANDARD FOR DATA
    SEMANTICS
    

    View Slide

61. GOOD
    API
    HOWEVER THESE ARE USUALLY NON-ISSUE WIHTIN
    CLOSED (ENTERPRISE) NETWORK
    

    View Slide

62. GOOD
    API
    GraphQL
    GraphQL out of the box provides
    Uniform Interface and thus
    results in systems with:
    1. Simplified Architecture
    2. Increased Components
    Visibility
    3. Decoupled Components
    

    View Slide

63. GOOD
    API
    GOOD
    API
    In fact, GraphQL is so good at providing UI, I
    wanted to take it and create the easiest way
    for everybody to get to the uniform interface…
    

    View Slide

64. GOOD
    API
    GOOD
    API
    http://deira.ai
    

    View Slide

65. GOOD
    API
    GOOD
    API
    Serverless API to provide Uniform Interface on
    top of existing data, functions and services
    http://deira.ai
    

    View Slide

66. GOOD
    API
    GOOD
    API
    http://deira.ai
    

    View Slide