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
2. GOOD API Zdenek Nemec API Consulting http://goodapi.co GOOD API @zdne zdne1
3. GOOD API GOOD API CONSULTING adidas API Guidelines https://adidas-group.gitbooks.io/api-guidelines
4. GOOD API UNIFORM INTERFACE What is Uniform Interface?
5. GOOD API ENGINEERING PRINCIPLE OF GENERALITY
6. GOOD API THE UNIFORM INTERFACE REFERS TO A STANDARD WAY TO DO SOMETHING REGARDLESS OF WHAT THE SPECIFIC ACTIVITY IS
7. GOOD API UNIFORM INTERFACE 1957 2017
8. GOOD API UNIFORM INTERFACE
9. GOOD API TERM COINED BY ROY T. FIELDING IN 2000
10. GOOD API SOFTWARE ENGINEERING PRINCIPLE OF GENERALITY APPLIED TO INTERFACE COMPONENT OF A COMPONENT IN DISTRIBUTED SYSTEM
11. GOOD API A CONSISTENT, PREDICTABLE WAY TO QUERY DATA AND EXERCISE ACTIONS REGARDLESS OF THE APPLICATION DOMAIN
12. GOOD API MANIFESTS AS ARCHITECTURAL STYLE CONSTRAINT TO ACHIEVE SOME DISTRIBUTED SYSTEM PROPERTIES
13. GOOD API WHY WE WANT UI System properties when we apply the UI constraint(s)
14. GOOD API THE BENEFITS OF UI
15. GOOD API SIMPLIFIED ARCHITECTURE
16. GOOD API IMPROVED VISIBILITY OF INTERACTIONS
17. GOOD API DECOUPLED COMPONENTS Enable parts to evolve independently Abstraction Layer Comp-A Comp-B no welding of components
18. GOOD API IMPROVED INTEROPERABILITY Reduces the cost of integration Two different drivers can drive any car
19. GOOD API REUSABLE CLIENT COMPONENTS Reduces development costs and time to market
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
21. GOOD API ENABLES AUTONOMOUS SERVICE DISCOVERY
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.”
23. GOOD API ENABLES FOR GENERAL AI
24. GOOD API UNIVERSE OF CAPABILITIES http://viv.ai
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…
26. GOOD API THE TRADEOFF OF UI
27. GOOD API DEGRADED EFFICIENCY UI Transformation Comp-A Comp-B Transformation
28. GOOD API UNLESS YOU ARE REALLY COUNTING BITS, WATTS OR MILLISECONDS THE UI’S BENEFITS OUTWEIGHS THE TRADEOFF
29. GOOD API THE QUEST SO FAR
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)
31. GOOD API SOAP
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
33. GOOD API REST
34. GOOD API REST ARCHITECTURAL STYLE
35. GOOD API REST UI CONSTRAINTS • Identification of Resources • Manipulation Through Representations • Self Descriptive Messages • HATEOAS
36. GOOD API
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
38. GOOD API RESTFUL WEB APIS RESTful Web APIs by Leonard Richardson & Mike Amundsen
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
40. GOOD API FUNCTION LIBRARIES
41. GOOD API FUNCTION LIBRARIES StdLib Algorithmia FaaS with Uniform Function Interface
42. GOOD API FUNCTION LIBRARIES FaaS with Uniform Function Interface
43. GOOD API QUERY LANGUAGES
44. GOOD API SQL IS THE UNIFORM INTERFACE TO RETRIEVE AND MANIPULATE DATA REGARDLESS OF WHAT THE DATA ARE
45. GOOD API QUERY LANGUAGES GraphQL Graql SPARQL Query language as the uniform interface
46. GOOD API GraphQL
47. GOOD API BENEFITS
48. GOOD API A CONSISTENT WAY TO QUERY DATA AND EXERCISE AFFORDANCES (MUTATIONS)
49. GOOD API FOUNDATION FOR REUSABLE CLIENT Relay, Apollo, Loki
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
51. GOOD API SCHEMA (DESIGN) FIRST
52. GOOD API DATA & AFFORDANCES INTROSPECTION AT RUNTIME
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/
54. GOOD API MYTH: OVERFETCHING If you are worried about over-fetching you are probably using wrong protocol. GraphQL
55. GOOD API TRADEOFFS
56. GOOD API ONLY JSON REPRESENTATION
57. GOOD API MISSING SOME OF THE REST SYSTEM QUALITIES COD & $ which translates to the loss of extensibility and cache-ability
58. GOOD API NO AUTH STANDARD
59. GOOD API TIED TO UI DATA STRUCTURE
60. GOOD API NO STANDARD FOR DATA SEMANTICS
61. GOOD API HOWEVER THESE ARE USUALLY NON-ISSUE WIHTIN CLOSED (ENTERPRISE) NETWORK
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
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…
64. GOOD API GOOD API http://deira.ai
65. GOOD API GOOD API Serverless API to provide Uniform Interface on top of existing data, functions and services http://deira.ai
66. GOOD API GOOD API http://deira.ai