Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Api presentation


Published on

Published in: Technology

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)● 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● ...(?)
  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?