How to build a successful API

To be a successful platform you don’t just need an API – you need an API that’s fast, usable, and easy to consume by humans and machines.

Transcript

1. FAST SECURE FAST SECURE USABLE APIS: USABLE APIS: BUILD BUILD APIS THAT PEOPLE USE APIS THAT PEOPLE USE WITH WITH NODE.JS AND NODE.JS AND HACKS THAT WIN HACKS THAT WIN WITH WITH OPEN DATA OPEN DATA #nodejs #api #opendata #hackthenorth codx.ca/hackthenorth ahmadnassri.com 1
2. HELLO! HELLO! 2 . 1
3. GET /who HTTP/1.1 Host: www.ahmadnassri.com Accept: application/json HTTP/1.1 200 OK Date: Sat, 17 Sep 2016 12:00:00 GMT Content­Type: application/json { "name": "Ahmad Nassri", "website": "http://www.ahmadnassri.com/", "twitter": "@AhmadNassri", "email": "ahmad@ahmadnassri.com", "bio": "Technologist, Entrepreneur, Dog Lover" } AHMAD NASSRI AHMAD NASSRI 2 . 2
4. GET /who HTTP/1.1 Host: joseph.by Accept: application/json HTTP/1.1 200 OK Date: Sat, 17 Sep 2016 12:00:00 GMT Content­Type: application/json { "name": "Joseph Bou­Younes", "website": "http://joseph.by/", "twitter": "@josephby", "email": "joseph.bouyounes@codx.ca", "bio": "Business, Tech, Data, Diapers" } JOSEPH BOU YOUNES JOSEPH BOU YOUNES 2 . 3
5. WHAT EXACTLY IS WHAT EXACTLY IS AN "API" ? AN "API" ? 3 . 1
6. “ In Egyptian mythology, Apis, is a bull-deity that was worshipped in the Memphis region. Apis served as an intermediary between humans and an all-powerful god. EGYPTOLOGY?! EGYPTOLOGY?! 3 . 2
7. “ an application programming interface (API) is a set of routines, protocols, and tools for building software applications. COMPUTER PROGRAMMING COMPUTER PROGRAMMING 3 . 3
8. WEB SERVICES WEB SERVICES “ A Web service is a method of communication between two electronic devices over a network. It is a software function provided at a network address over the web with the service always on. 3 . 4
9. RESTful Web APIs RESTful Web APIs REST (REpresentational State Transfer) is a simple stateless architecture style that generally runs over HTTP. 3 . 5
10. BEST PRACTICES BEST PRACTICES 4 . 1
11. BE BE FRIENDLY FRIENDLY TO THE TO THE DEVELOPER AND BE DEVELOPER AND BE EXPLORABLE EXPLORABLE VIA A VIA A BROWSER ADDRESS BAR BROWSER ADDRESS BAR 4 . 2
12. KEEP IT SIMPLE, KEEP IT SIMPLE, INTUITIVE INTUITIVE AND AND CONSISTENT CONSISTENT TO MAKE TO MAKE ADOPTION EASY & ADOPTION EASY & PLEASANT PLEASANT 4 . 3
13. PROVIDE ENOUGH PROVIDE ENOUGH FLEXIBILITY FLEXIBILITY TO POWER TO POWER THE MAJORITY OF USE THE MAJORITY OF USE CASES CASES 4 . 4
14. USE WEB USE WEB STANDARDS STANDARDS WHERE THEY MAKE WHERE THEY MAKE SENSE SENSE 4 . 5
15. STANDARDS STANDARDS 4 . 6
16. HYPERMEDIA HYPE HYPERMEDIA HYPE Collection+JSON Hypertext Application Language (HAL) ATOM 4 . 7
17. GET /player/1234567890 HTTP/1.1 { "@context": { "@vocab": "https://schema.org/", "image": { "@type": "@id" }, "friends": { "@type": "@id" } }, "@id": "https://api.example.com/player/1234567890", "playerId": "1234567890", "name": "Kevin Sookocheff", "alternateName": "soofaloofa", "image": "https://api.example.com/player/1234567890/avatar.png", "friends": "https://api.example.com/player/1234567890/friends" } JSON-LD JSON-LD 4 . 8
18. AUTHENTICATION AUTHENTICATION RFC 2617 4 . 9
19. # URL Versioning: GET /api/v2/foo HTTP/1.1 # Custom Header: GET /api/foo X-VERSION: 2 # Content Type GET: /api/foo Accept: application/vnd.github.v3.raw+json VERSIONING VERSIONING 4 . 10
20. NODEJS NODEJS STARTER KIT STARTER KIT 5 . 1
21. 5 . 2
22. 5 . 3
23. 6 . 1
24. YOUR API IS YOUR API IS A A PRODUCT PRODUCT! ! 6 . 2
25. FLEXIBLE FLEXIBLE INTUITIVE INTUITIVE CONSISTENT CONSISTENT PLEASANT PLEASANT EXPLORABLE EXPLORABLE STANDARDS STANDARDS 6 . 3
26. #OPENDATA #OPENDATA 7 . 1
27. OPEN DATA? OPEN DATA? "Open [data] means anyone can freely access, use, modify, and share the data for any purpose (subject, at most, to requirements that preserve provenance and openness)." - the Open Definition project It's the fastest and easiest way to bring the outside world into your hack. codx.ca/hackthenorth 7 . 2
28. WHAT CAN YOU GET? WHAT CAN YOU GET? Useful Examples! Building Permits Car Travel Speed Corporate Registration Information (Company Names, Addresses & Director Names) Parking Tickets Weather Forecasts codx.ca/hackthenorth 7 . 3
29. WHAT CAN YOU GET? WHAT CAN YOU GET? Level of Gov't Responsibilities Example Data Federal Agriculture, Financial Services, Economic Data, Natural Resources, CRA, Census, Weather Agriculture, Financial Services, Economic Data, Natural Resources, CRA, Census, Weather Criminal Code Weather GIS and Imagery Economic Data Tax Code Provincial Courts, Education, Environment, Energy, Health Care K-12 Curriculum Court Rulings Municipal Water, Traffic, Parking, Property Tax Property Tax Traffic Flows codx.ca/hackthenorth 7 . 4
30. WHAT CAN YOU GET? WHAT CAN YOU GET? WARNING: Data is often old, out of date, or inconsistent. LOOK FIRST codx.ca/hackthenorth 7 . 5
31. FINDING OPEN DATA FINDING OPEN DATA 1. codx.ca/hackthenorth codx.ca/hackthenorth 7 . 6
32. FINDING OPEN DATA FINDING OPEN DATA 2. Google codx.ca/hackthenorth 7 . 7
33. FINDING OPEN DATA FINDING OPEN DATA 3. Portals codx.ca/hackthenorth 7 . 8
34. FINDING OPEN DATA FINDING OPEN DATA 4. Check Usability Text Text Text NO! codx.ca/hackthenorth 7 . 9
35. FINDING OPEN DATA FINDING OPEN DATA 5. Download! codx.ca/hackthenorth 7 . 10
36. THANK YOU THANK YOU Twitter @AhmadNassri Slack @AhmadNassri Website / Blog AhmadNassri.com Twitter @josephby Slack @josephby RFTM codx.ca/hackthenorth 8