Api presentation


Published on

Published in: Technology
1 Like
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Api presentation

  1. 1. APIAn introduction
  2. 2. WEB REST JSON API● WEB - Set of HTTP Endpoints● REST - Descriptive URLs, nouns and verbs, emphasis on readability● JSON - Output format (JavaScript Object Notation)● API - Application Programming Interface
  3. 3. Other WS-Protocols● SOAP● XML-RPC● ...● Clean protocol (less complexity)● Reduces overhead of XML envelopes creation/handling
  4. 4. Other Output Formats● XML● CSV● ...● Less verbosity● Client direct interaction (most clients handle Javascript/JSON interaction)
  5. 5. Who is it for?● Desktop Applications● Mobile Applications● Third-Party Web Applications● Everything that HTTPsPurposeInteraction of external services with ourbackend
  6. 6. Who is it for? (2)End UserClient Service Developer TeamGoalMaximize end user productivity
  7. 7. Modules● Input - Output - Error Output● Documentation● User/App Identification
  8. 8. Input - Output - Error OutputThink of each HTTP Endpoint as a method● What should it receive?● What should it respond/return?● How should it behave when something was unexpected?
  9. 9. Input - Output - Error Output (2)http://api.platform.com/banjos/1● What it received ○ 1 (identifier of the banjo)● What will it respond? ○ Depends of your design decision, as long as its JSON (ex: {“state” : “ok”, “banjo” : {“id” : 1, “brand”: “Les Paulanjo”}}● How should it handle errors? ○ Depends of your design decision, as long as its JSON (ex: {“state” : “error”, “error” : “No banjo 1”}
  10. 10. Input - Output - Error Output (3)In Rightclearing:All responses have a “state” parameter (possible valueseither “ok” or “error”)GET - response definition per resource/actionPOST - returns Id of the newly-created resourcePUT - nothing relevantDELETE - nothing relevant
  11. 11. Input - Output - Error Output (4)Errors In Rightclearing:● single error: ○ error: error code ○ error_description: error message ○ error_uri: uri for the error documentation● multiple errors: ○ errors: collection of errors ○ for each error: ■ code: error code ■ messages: collection or error messages ■ uri: uri for the error documentation
  12. 12. Input - Output - Error Output (5)Room for Improvement● “single error” spec is only used by Oauth endpoints (follows its spec)● “multiple errors” spec is used everywhere else (convention/ience for multiple validation message problem)Could one find a standardization of error messages?This might get confusing
  13. 13. DocumentationUnder construction...● APIs are not Apps (no incremental learning here, no navigating)● End User must know what can he use, how can he use, where can he use.Straightforwardness is the key - be very clearand concise in describing functionality
  14. 14. Documentation (2)For each endpoint:● Description● Route● Request Method● Request Headers● Request Parameters● Response Headers● Response Body● Example
  15. 15. Documentation (3)For each error (still under development):● Description● Solutions/Workarounds● ...(?)https://docs.google.com/document/d/1daK5zRlPZDQ2tV6TFUgibEmejLjrkSavD_6ktU0hpQE/edit
  16. 16. User/App IdentificationMany approaches:● app password● Open ID● Oauth● etc...
  17. 17. User/App Identification(Oauth)● Manager owns resources in Rightclearing (Resource Owner)● Allows binding of Resource Owner’s accounts in other services with his Rightclearing Account (easy identification)● Resource Owner can define a set of permissions per client application● Resources are the Resource Owner’s responsibility
  18. 18. User/App Identification(Oauth) (2)● Doesnt provide security (SSL does)● Authorization Protocol, yet needs authentication● ...● no clear better alternative● a lot of existing libraries on the protocol in most of programming languages
  19. 19. API Application Ecosystem● Framework - Sinatra● Common modules libraries - rc-logic● Architecture - MVDispatcher / Façade● SDKs - rc-sdk-ruby (for now)● Integration - Oauth Authorizations
  20. 20. Framework - SinatraAdvantages● Minimal● Thread-safe● Does not make assumptions● Flexible● Lots of extensions / well-developed ecosystem● Supports HTTP very well
  21. 21. Framework - Sinatra (2)Disadvantages● Sinatra specific, found none, maybe later(Rails dependent behaviour in certain gems are more agem-specific disadvantage than the other way round)
  22. 22. Common modules librariesrc-logic● We want to process user input, access/handle resources, provide JSON output● Sinatra/Ruby handle user input/output, AR/filesystem libraries handle resourcesData Integrity must be kept cross-application (aresource in the API is the same as in the mainweb app)
  23. 23. Common modules librariesrc-logic (2)What is shared?● Common Data Model Mapping / Integration● Common Data Model/File handling libraries● Common configuration (database conf, app conf, filesystem conf)
  24. 24. Architecture - MVDispatcher /Façade● Models - API-specific models or Extensions of common models with API-specific behaviour● Views - Handle model view representation (JSON-visible attributes, model delegations, attribute formatting)● Helpers - encapsulated logic from filters/routes conveniently packed● Filters - route pre-filtering● Apis - Façades for sub-components/APIs● API - Where everything is bound
  25. 25. Architecture - MVDispatcher /Façade (2)
  26. 26. SDKs - rc-sdk-rubyLibrary to ease the integration of a possibleexternal app with the API using language-specificHTTP/Oauth libraries.● Two Entities - App and User● DSL for building REST Requests● Provides Responses HandlingExisting SDK only for Ruby (already used forrestorm integration with the API)
  27. 27. SDKs - rc-sdk-ruby (2)Javascript SDK(???)(Java? PHP? Python? etc...)
  28. 28. IntegrationProvides API access to external clients● Handled in the Web App (Oauth flow)● Web App supplies resource owner authorizations● API delivers access tokens
  29. 29. Integration (2)
  30. 30. Questions?