Post on 15-Jul-2015
We are API fanatics. We are API hustlers. We build API tools.
UNIRESTAPIANALYTICS
getKONG
Interested in building API management tools:Proxies, Reverse proxies, Caching, Analytics,
UserManagement but also a friendly Market Place
100.000 API developers, thousands of APIs
IMPORTANT API NOTICE
• Everyone should use APIs: API economy, & API centric design
• APIs don’t have to be public
• If you don’t use APIs in 2015 you’re doing something wrong
LET’S DO THIS
• Introduction
• Architectures
• Endpoints
• Building
• Monetizing
• Marketing
• A look at the future…
EVERYONE WANTS TO WIN• A painless experience for consumers
• Return data in simple flexible format (JSON vs XML)
• Insightful Errors
• Does what it says…right?
API ARCHITECTURE
• REST (good)
• SOAP (uh-oh)
• RPC (lol)
• hyperREST (HATEOAS) - the unwanted child
• IDGAF (yolo)
RESTREST is not a standard but makes consumption of APIs faster, its CRUD.REST uses plain HTTP with JSON, mostly
REST can be cached
Natural to developers, SDKs, Docs
BLUEPRINTS
• Think as a Dev, Think use-cases
• RAML, APIBLUEPRINT, SWAGGER
• Worth the time WADL -> XMLSwagger -> JSONIODocs -> JSONRestDoc -> JSONAPIBlueprint -> MarkdownRAML -> YAML
SOAP- Independent of transport protocol (HTTP, FTP, UDP)
- XML
- SOAP Messages are envelopes (data,actions,headers,errors)
- Not just SSL but WS-Security
- Self-discoverable (WSDL) Self-retrying (WS-ReliableMessaging)
Some scenarios are ok..
MEANINGFUL URL
https://domain.com/api/path/something
Namespace Base resource Resource ID
Entry-point
..CAN GET COMPLEX
https://myapi.com/users/12e584/email.json
Namespace Base resource
Resource ID
Specific Resource
https://myapi.com/get_email_for/bob@mail.com
QUERY FILTERS
GET http://api.twitter.com/1/statuses/home_timeline.json?since_id=9999&max_id=1259
What is the best practice?
GET http://api.blog.com/v1/articles/1234/comments
GET http://api.blog.com/v1/comments?article=1234
USE VERBS
POST, GET, PUT, DELETE are kings
GET /customers/7236/invoices
CANIHAS /customers/7236/invoices
VS
RESPONSES{
"type": "car", "name": “My Ferrari",
"cylinders": 512, "options": { "seats": 4,
"turbospeed": 360 },
"allowedpassengers": { "family": ["Alice", “Bob”],“friends”:[“Charlie,Diana”]
}}
RESPONSES<car xmlns:xs="http://www.w3.org/2001/XMLSchema">
<name type="xs:string">My Ferrari</name> <cylinders type="xs:int">48</cylinders>
<optionals> <seats type="xs:int">4</seats>
<turbospeed type="xs:int">360</turbospeed> </optionals>
<allowedpassengers> <devices type="xs:list">
<device type="xs:string">cdrom</device> <device type="xs:string">harddisk</device>
</allowedpassengers> </boot>
</vm>
RESPONSESCareful of Polymorphism
{ “fullname": "Peter File","user": {"username": "PeFile","userid": 123}
{ "username": “PeFile", "fullname": "Peter File", }
AUTHENTICATION“Track Usage, Secure data”
Oauth (different versions)Basic authentication
Token Header
Key-in-the-bodyQuerystring
MOCKFake it till you make it
var Interfake = require('interfake');var interfake = new Interfake();
interfake.get('/users').status(200).body({ users: [ { id: 1, name: 'BOB 1' } ] });
interfake.get('/users/1').status(200).body({ id: 1, name: 'BOB' });var postResponse = interfake.post('/
users').status(201).body({ created : true });postResponse.creates.get('/users/2').status(200).body({ id: 2, name:
'ALICE' });postResponse.extends.get('/users').status(200).body({ items: [ { id: 2,
name: 'ALICE' } ] });
interfake.listen(1337);
MOCKFake it till you make it
$ curl http://localhost:1337/users -X GET
200{
"users" : [ {
"id":1 "name":"BOB"
} ]}
FRAMEWORKSUse them.
Rails/Rails-ApiExpress (Node)
Hapi (Node)Node-Restify
Flask(Python) / Flask-Restful (thx Twilio)Falcon (Python)Pecan (Python)
Werkzeug(Python)Interfake (Node - @basicallydan )
slimframework (PHP)Laravel (PHP)
$ > wrk -t12 -c400 -d30s http://127.0.0.1:8080/index.html
$ > Running 30s test @ http://127.0.0.1:8080/index.html 12 threads and 400 connections Thread Stats Avg Stdev Max +/- Stdev Latency 635.91us 0.89ms 12.92ms 93.69% Req/Sec 56.20k 8.07k 62.00k 86.54% 22464657 requests in 30.00s, 17.76GB read Requests/sec: 748868.53 Transfer/sec: 606.33MB
DEV DOCS
Ex: Let’s analyse https://developer.github.com/v3/repos/collaborators/
–Paddy Foran
“Good API design is not a matter of following principles, it’s a matter of fulfilling your users’
expectations while trying to maintain technical and semantic purity”
• Design intuitive APIs, aimed for instant consumption with scalable stacks
• Use logs and do tests. Analyse what endpoints are used most and learn from it.
• Think of how developers will use your API. Find use-cases and illustrate them in the docs.
• By finding most common uses cases you can then make endpoints that make sense.
• Create a great developer experience by talking with your user-base.
TOOLS TO HAVE
• wrk - Stress test from the comfort of your localhost
• https://loader.io/ - LOAD TESTING
• https://www.blitz.io/ - GEO LOAD TESTING
• https://github.com/jakubroztocil/httpie - f**ks cURL CLI
• https://www.getpostman.com/ - f**ks the CLI
• http://luckymarmot.com/paw - f**ks the browser (macos)
FURTHER READING
• http://restcookbook.com/HTTP%20Methods/idempotency/
• http://mark-kirby.co.uk/2013/creating-a-true-rest-api/
• http://buff.ly/1vY4OsT
• http://swaxblog.tumblr.com/post/112611863175/who-cares-about-get-vs-post-norest
• https://www.youtube.com/watch?v=Pn9ucXr04r8
• https://speakerdeck.com/treeder/how-to-build-a-scalable-api