API Nuts & Bolts

Georg Leciejewski SalesKing GmbH

Why API & oAuth

I believe in FREEDOM of

Ideas - anybody can enhance or model a plattform around his needs Code - anybody can use and improve it Data - choose what to do & where to go with your data Use adapt the Look & feel, access from any device, anywhere

Connectivity RULEZ So many new & moving targets You cannot and don't want to build everything

Parts

Enpoint concept Data-Protocol Versioning Security Oauth & Apps

Endpoint Thoughts

Uri design Versioning internals(not data) Provide metadata Pagination Filtering Caching Security Errors & Validations

Some Advice

Use separate API-Controllers Stay mostly RESTfull Nest resources only where it makes sence Filtering by filter[] param hash Provide metadata and discovery-links

For collections /index For single objects

Thoughts on Data Description

Internal vs. External Model Representation Where to define:

Object properties Object links

Versioning Where to publish docs Hate WSDL

JSON-Schema to the rescue

simple Human and machine readable format Define Object properties & links Validation Documentation Versioning Automated model2schema

JSON Schema Advice

Host it in public github Fully rely on it internaly

For output model2schema Input validation, param cleaning, field/prop delivery

separate description of api & data from core(models/controllers) Deliver /schema, oders/schema&v=1.0 Examples

Versioning

What to version

Changes in object properties, endpoints links model & controller internals

Version everything is nearly impossible and might be senseless Keep it simple

Version your schema holding 90% of the changes Let people follow your public development Folder & filenames ? Gem version

Security - Quicky

Internal vs. API Authorization

is_admin?, Roles&Rights, ACL, App-login HttpBasicAuth vs. API-Token vs. Oauth vs .

Authentification

Request limits people running tests against your live env

Oauth2 & Apps

oAuth without apps is no fun, BUT apps force you to build a different kind of software AppStore You need an ACL/Role System External vs. Internal(canvas) apps

Why oAuth

Greater controll of api-clients

Know who is using which app: admin, group-admins, user and be able to block api-clients Know what an api-client is doing since each app must define it's needed rights/scope Bundle & develop them to customers needs Keep your core clean Let others enhance your software Make more money

Dissect your software into smaller parts

Apps enforce

Good roles & rights model Interface for dev's to create their own apps Interface for users for find and manage their apps Admin area to allow apps for some users, groups or global Keep an eye on external dev's, code business models: Terms of Service

oAuth2 Problems

Client libs are rare and maybe outdated Moving target => current draft v2.16 Most libraries are trying to adapt all available services(google, fb, twitter,......) == overhead Steep learning curve for internal & ext. Dev's Which controll/login flows do you want to support?

Oauth advice

Document your internals Provide examples in different programming languages Build a playground Open source your internally used libs Think twice about your rights-system Build your own oauth-helper lib / SDK Have external dev's programm apps early