Hackathons have boomed, people attending such events have been consuming thousands of APIs to power their creative projects. However, not everyone can consume APIs like a boss. Companies spend hundreds of thousands of dollars in promoting and ensuring best practices are followed when building APIs. In this talk I will give you an overview of how to build a potentially successful API overnight, like hackathoneers do. A recipe for success as a takeaway from this talk will be shared. Topics covered: Evolution of APIs, Hackathons, REST API Frameworks, API Design, API Editors, API Management.

1. BUILDING A SUCCESSFUL
API OVERNIGHT
@orliesaurus

2. BUILDING A SUCCESSFUL
API OVERNIGHT
@orliesaurus

3. @orliesaurus
orlando@mashape.com

4. We are API fanatics. We are API hustlers.
We build API tools.
UNIREST
APIANALYTICS
getKONG

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

6. HACKATHONS ARE COOL

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

8. LET’S DO THIS
• Introduction
• Architectures
• Endpoints
• Building
• Monetizing
• Marketing
• A look at the future…

9. FROM 0 TO 100
To build something powerful you have to spend time
designing it properly

11. DEVELOPERS ARE LAZY
Architectural decisions

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

14. DEVELOPER EXPERIENCE
DX - GO BIG OR GO HOME

15. API ARCHITECTURE
• REST (good)
• SOAP (uh-oh)
• RPC (lol)
• hyperREST (HATEOAS) - the unwanted child
• IDGAF (yolo)

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

17. BLUEPRINTS
• Think as a Dev, Think use-cases
• RAML,APIBLUEPRINT, SWAGGER
• Worth the time WADL -> XML
Swagger -> JSON
IODocs -> JSON
RestDoc -> JSON
APIBlueprint -> Markdown
RAML ->YAML

18. DESIGN EDITORS

19. DESIGN EDITORS

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

22. ENDPOINTS SCIENCE
Paint a pretty picture

23. MEANINGFUL URL
https://domain.com/api/path/something
Namespace Base resource Resource ID
Entry-point

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

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

26. USE VERBS
POST, GET, PUT, DELETE are kings
GET /customers/7236/invoices
CANIHAS /customers/7236/invoices
VS

27. USE VERBS

28. USE MORE VERBS
HEAD, OPTIONS, PATCH are available
PUT
PATCH
VS

30. HEADERS
An unseen blade is deadly

31. HEADERS
Ex:
Accept:
Content-Type:
Accept-Charset:
Authorisation:
Cache-Control:
ETag

32. HEADERS
Should we put API versions in the header?
Accept: application/vnd.steveklabnik-v2+json

33. RESPONSES
The good stuff

34. ERRORCODES
Make ‘em mean something

35. RESPONSES
{
"type": "car",
"name":“My Ferrari",
"cylinders": 512,
"options": {
"seats": 4,
"turbospeed": 360
},
"allowedpassengers": {
"family": ["Alice",“Bob”],
“friends”:[“Charlie,Diana”]
}
}

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

37. RESPONSES
“I’m so sorry…”
- every company returning XML

38. RESPONSES

39. RESPONSES
Careful of Polymorphism
{
“fullname": "Peter File",
"user": {
"username": "PeFile",
"userid": 123
}
{
"username":“PeFile",
"fullname": "Peter File",
}

40. AUTHENTICATION
All your bases are belong to us

41. AUTHENTICATION
“Track Usage,
Secure data”
Oauth (different versions)
Basic authentication
Token
Header
Key-in-the-body
Querystring

42. BUILDING
Small steps, like lasagne

43. MOCK
Fake it till you make it

44. MOCK
Fake 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);

45. MOCK
Fake it till you make it
$ curl http://localhost:1337/users -X GET
200
{
"users" : [
{
"id":1
"name":"BOB"
}
]
}

46. MOCK
Fake it till you make it
$ curl http://localhost:1337/users -X POST
201
{
"created":true
}

47. FRAMEWORKS
Use them.
Rails/Rails-Api
Express (Node)
Hapi (Node)
Node-Restify
Flask(Python) / Flask-Restful (thxTwilio)
Falcon (Python)
Pecan (Python)
Werkzeug(Python)
Interfake (Node - @basicallydan )
slimframework (PHP)
Laravel (PHP)

48. STRUCTURE
http://jsonapi.org/

49. MICROSERVICES

50. RELIABILITY
Load balancing to the win

51. SCALING
There’s only a single direction…
Stateless
Minimal
Idempotent
Can afford errors

52. VERSIONING
Iterate, Iterate, Iterate

53. TEST & DEBUG
Nothing is perfect
APIANALYTICS
wrk
SPLUNK
LOGSTASH

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

56. MONETIZING
Everything comes with a price

57. UTOPIA
FREE

58. UTOPIA
FREE
Facebook
Amazon
Salesforce
Twitter
Shopify

59. LET’S BE HONEST
FREEMIUM
Ex:
Mailgun
Twilio
Google Maps

60. INTENSE
PAID

61. PROVIDER PAYS
Money Pot for Developers

62. MARKETING
Reaching out to devs, like a boss.

63. EVENT STRATEGY
How to promote your API

64. HACKATHONS
The best way to gather feedback on your API

65. FIND GOOD HACKATHONS
As a developer you don’t have time to waste attending
bad hackathons

66. PREPARE
Swag packs (t-shirts and stickers), discount, codes, prizes

67. BE A FRIEND
Don’t be a salesman

68. CONFERENCES
Set up a booth, find partners

69. TRACKING & ANALYTICS
Signups
Endpoint usage
Referrals/Coupons tracking
Documentation analytics

70. DOCS & DEMOS
Build proof of concepts, great documentation, demos and
make it easy to be reached

71. SDKS
Automate them

72. DEV DOCS
Ex: Let’s analyse https://developer.github.com/v3/repos/
collaborators/

73. BUILD INTEGRATIONS
Yet another way to market APIs

74. –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”

75. RECAP
Time to wrap it up

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

77. @orliesaurus
orlando@mashape.com

78. TOOLS TO HAVE
• wrk - Stress test from the comfort of your localhost
• https://loader.io/ - LOADTESTING
• https://www.blitz.io/ - GEO LOADTESTING
• 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)

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