1. API
An introduction

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. Other WS-Protocols
● SOAP
● XML-RPC
● ...
● Clean protocol (less complexity)
● Reduces overhead of XML envelopes
creation/handling

4. Other Output Formats
● XML
● CSV
● ...
● Less verbosity
● Client direct interaction (most clients handle
Javascript/JSON interaction)

5. Who is it for?
● Desktop Applications
● Mobile Applications
● Third-Party Web Applications
● Everything that HTTPs
Purpose
Interaction of external services with our
backend

6. Who is it for? (2)
End User
Client Service Developer Team
Goal
Maximize end user productivity

7. Modules
● Input - Output - Error Output
● Documentation
● User/App Identification

8. Input - Output - Error Output
Think 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. 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. Input - Output - Error Output (3)
In Rightclearing:
All responses have a “state” parameter (possible values
either “ok” or “error”)
GET - response definition per resource/action
POST - returns Id of the newly-created resource
PUT - nothing relevant
DELETE - nothing relevant

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. 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. Documentation
Under 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

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

15. Documentation (3)
For each error (still under development):
● Description
● Solutions/Workarounds
● ...(?)
https://docs.google.
com/document/d/1daK5zRlPZDQ2tV6TFUgibEmejLjrkSavD_6ktU0hpQE/edit

16. User/App Identification
Many approaches:
● app password
● Open ID
● Oauth
● etc...

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. 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

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. Framework - Sinatra
Advantages
● Minimal
● Thread-safe
● Does not make assumptions
● Flexible
● Lots of extensions / well-developed
ecosystem
● Supports HTTP very well

21. 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)

22. 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)

23. 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)

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. Architecture - MVDispatcher /
Façade (2)

26. SDKs - rc-sdk-ruby
Library 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)

27. SDKs - rc-sdk-ruby (2)
Javascript SDK(???)
(Java? PHP? Python? etc...)

28. Integration
Provides API access to external clients
● Handled in the Web App (Oauth flow)
● Web App supplies resource owner
authorizations
● API delivers access tokens

29. Integration (2)

30. Questions?