Share
Embed
Developing web REST API
Shalva Usubov
October 11, 2014
Transcript
33 slides
-
Application Programming Interface • Want to scale integration with customers
and partners • Need a mobile app • Migrate on Service-oriented architecture • ... -
• HTTP (methods, status, headers) • REST • Representation •
Versioning • Security • Performance • Caching -
HTTP methods GET fetch a resource representation POST create a
resource PUT update a resource PATCH partially update a resource DELETE remove a resource ... -
HTTP status codes 200 OK 304 Not Modified 400 Bad
Request 401 Unauthorized 403 Forbidden 404 Not Found 500 Internal Server Error 502 Bad Gateway -
HTTP request and response headers Content-Type Content-Language Content-Length Content-Encoding Last-Modified
Cache-Control Location ETag Vary Expires If-Modified-Since If-None-Match -
Security Prefer HTTPS • OAuth - most flexible • Basic
HTTP Authentication • Custom -
REST Representational State Transfer Uses URLs to identify resources HTTP
verbs indicate the action to perform -
REST Method (verbs) URL Description GET /gists Returns all gists
POST /gists Create new gist GET /gists/1 Return given gist PATCH /gists/1 Update given gist DELETE /gists/1 Delete given gist -
REST Example GET https://api.github.com/gists POST https://api.github.com/gists GET https://api.github.com/gists/6412448 PATCH https://api.github.com/gists/6412448
DELETE https://api.github.com/gists/6412448 -
REST hierarchical association GET https://api.github.com/gists/6412448/commits POST https://api.github.com/gists/6412448/commits GET https://api.github.com/gists/6412448/commits/1 PATCH
https://api.github.com/gists/6412448/commits/1 DELETE https://api.github.com/gists/6412448/commits/1 -
REST filters, search and pagination GET https://api.github.com/gists?status=regular GET https://api.github.com/gists?public=true GET
https://api.github.com/gists?q=something GET https://api.github.com/gists?page=2&per_page=20 -
XML eXtensible Markup Language • Verbose • Includes data type
information • Powerful/Complicated -
XML <photo id="2733" favorite="0" license="3" rotation="90" original format="png"> <owner nsid="12037949754@N01"
username="Bees" location="Bedford, UK" /> <title>orford_castle_taster</title> <description>hello!</description> <visibility ispublic="1" isfriend="0" isfamily="0" /> <tags> <tag id="1234" author="12037949754@N01" raw="woo yay">wooyay</tag> <tag id="1235" author="12037949754@N01" raw="hoopla">hoopla</tag> </tags> </photo> -
JSON JavaScript Object Notation • Widely support in programming languages
• Human readable • No data type information -
JSON { "url": "https://api.github.com/gists/6412448", "commits_url": "https://api.github.com/gists/6412448/commits", "id": "6412448", "public": true,
"owner": { "login": "shaliko", "id": 36139, "avatar_url": "https://avatars.githubusercontent.com/u/36139?v=2", "url": "https://api.github.com/users/shaliko", } } -
Content Negotiation Client says what formats it can handle, and
the server works out what is best Accept: application/json;q=1.0, application/xml;q=0.6 -
HTTP caching Expires for statics content # Response Expires: Sun,
09 Aug 2015 10:56:14 GMT Cache-Control: max-age=36000,public -
HTTP caching Conditional policy for dynamic content # Response ETag:
"f6373f0fd7ccb539c6ec8f5991dddc30" Last-Modified: Wed, 08 Oct 2014 06:32:07 GMT -
HTTP caching $ curl -I https://api.github.com/gists/6412448 HTTP/1.1 200 OK Server:
GitHub.com Date: Sat, 11 Oct 2014 02:05:35 GMT Content-Type: application/json; charset=utf-8 Status: 200 OK Cache-Control: public, max-age=60 Last-Modified: Thu, 09 Oct 2014 10:58:09 GMT ETag: "82fc020c8b1e99c9562fed6ba56e8230" Content-Length: 2499 Vary: Accept, Accept-Encoding -
HTTP caching $ curl -I https://api.github.com/gists/6412448 HTTP/1.1 200 OK Server:
GitHub.com Date: Sat, 11 Oct 2014 02:05:35 GMT Content-Type: application/json; charset=utf-8 Status: 200 OK Cache-Control: public, max-age=60 Last-Modified: Thu, 09 Oct 2014 10:58:09 GMT ETag: "82fc020c8b1e99c9562fed6ba56e8230" Content-Length: 2499 Vary: Accept, Accept-Encoding -
HTTP caching $ curl -I https://api.github.com/gists/6412448 -H 'If-None-Match:" 82fc020c8b1e99c9562fed6ba56e8230"' HTTP/1.1
304 Not Modified Server: GitHub.com Date: Sat, 11 Oct 2014 02:14:37 GMT Status: 304 Not Modified Cache-Control: public, max-age=60 Last-Modified: Thu, 09 Oct 2014 10:58:09 GMT ETag: "82fc020c8b1e99c9562fed6ba56e8230" Vary: Accept, Accept-Encoding -
HTTP caching $ curl -I https://api.github.com/gists/6412448 -H 'If-None-Match:" 82fc020c8b1e99c9562fed6ba56e8230"' HTTP/1.1
304 Not Modified Server: GitHub.com Date: Sat, 11 Oct 2014 02:14:37 GMT Status: 304 Not Modified Cache-Control: public, max-age=60 Last-Modified: Thu, 09 Oct 2014 10:58:09 GMT ETag: "82fc020c8b1e99c9562fed6ba56e8230" Vary: Accept, Accept-Encoding Cut response time -
HTTP caching $ curl -I https://api.github.com/gists/6412448 -H "If-Modified-Since: Thu, 09
Oct 2014 10:58:09 GMT" HTTP/1.1 304 Not Modified Server: GitHub.com Date: Sat, 11 Oct 2014 02:14:37 GMT Status: 304 Not Modified Cache-Control: public, max-age=60 Last-Modified: Thu, 09 Oct 2014 10:58:09 GMT ETag: "82fc020c8b1e99c9562fed6ba56e8230" Vary: Accept, Accept-Encoding -
Error handling Code for code, message for people HTTP/1.1 400
Bad Request { "code": 34, "message": "Missing required field", "url": "https://developers.example.com/errors/34" } -
Performance • Cache on client and server sides • HTTP
compression • Delay async tasks • SPDY/HTTP 2.0 - N+1 over HTTP is expensive -
Start from • RESTful Web Services Cookbook By: Subbu Allamaraju
• Web API Design by Brian Mulloy (apigee) • http://jsonapi.org • GitHub API https://developer.github.com/v3/