APIAn introduction

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

Other WS-Protocols● SOAP● XML-RPC● ...

● Clean protocol (less complexity)● Reduces overhead of XML envelopes

creation/handling

Other Output Formats● XML● CSV● ...

● Less verbosity● Client direct interaction (most clients handle

Javascript/JSON interaction)

Who is it for?● Desktop Applications● Mobile Applications● Third-Party Web Applications● Everything that HTTPs

Purpose Interaction of external services with our backend

Who is it for? (2)End UserClient Service Developer Team

Goal Maximize end user productivity

Modules

● Input - Output - Error Output● Documentation● User/App Identification

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?

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”}

Input - Output - Error Output (3)In Rightclearing:

All responses have a “state” parameter (possible values either “ok” or “error”)

GET - response definition per resource/actionPOST - returns Id of the newly-created resourcePUT - nothing relevantDELETE - nothing relevant

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

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

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 clear and concise in describing functionality

Documentation (2)For each endpoint:● Description● Route● Request Method● Request Headers● Request Parameters● Response Headers● Response Body● Example

Documentation (3)For each error (still under development):● Description● Solutions/Workarounds● ...(?)

https://docs.google.com/document/d/1daK5zRlPZDQ2tV6TFUgibEmejLjrkSavD_6ktU0hpQE/edit

User/App IdentificationMany approaches:● app password● Open ID● Oauth● etc...

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

User/App Identification(Oauth) (2)● Doesn't 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

API Application Ecosystem● Framework - Sinatra

● Common modules libraries - rc-logic

● Architecture - MVDispatcher / Façade

● SDKs - rc-sdk-ruby (for now)

● Integration - Oauth Authorizations

Framework - SinatraAdvantages

● Minimal● Thread-safe● Does not make assumptions● Flexible● Lots of extensions / well-developed

ecosystem● Supports HTTP very well

Framework - Sinatra (2)Disadvantages

● Sinatra specific, found none, maybe later

(Rails dependent behaviour in certain gems are more a gem-specific disadvantage than the other way round)

Common modules libraries rc-logic

● We want to process user input, access/handle resources, provide JSON output

● Sinatra/Ruby handle user input/output, AR/filesystem libraries handle resources

Data Integrity must be kept cross-application (a resource in the API is the same as in the main web app)

Common modules libraries rc-logic (2)What is shared?

● Common Data Model Mapping / Integration● Common Data Model/File handling libraries● Common configuration (database conf, app

conf, filesystem conf)

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

Architecture - MVDispatcher / Façade (2)

SDKs - rc-sdk-rubyLibrary to ease the integration of a possible external app with the API using language-specific HTTP/Oauth libraries.

● Two Entities - App and User● DSL for building REST Requests● Provides Responses Handling

Existing SDK only for Ruby (already used for restorm integration with the API)

SDKs - rc-sdk-ruby (2)

Javascript SDK(???)(Java? PHP? Python? etc...)

IntegrationProvides API access to external clients

● Handled in the Web App (Oauth flow)● Web App supplies resource owner

authorizations● API delivers access tokens

Integration (2)

Questions?