Web API in Android World

I gave a talk at Android All Stars @dots on Aug. 8th, 2015.

In this talk, I described what is a good Web API for Android App. and some best practices an API developer has to take care of.

References:
- The future of API design: The orchestration layer
http://thenextweb.com/dd/2013/12/17/future-api-design-orchestration-layer/
- Google JSON Style Guide
http://google-styleguide.googlecode.com/svn/trunk/jsoncstyleguide.xml
- API Design and Development @ APIStrat Amsterdam
https://www.youtube.com/watch?v=8BsrAblL23U
- The Netflix Dynamic Scripting Platform
http://techblog.netflix.com/2014/03/the-netflix-dynamic-scripting-platform.html
- GraphQL Introduction

http://facebook.github.io/react/blog/2015/05/01/graphql-introduction.html
- REST APIs must be hypertext-driven
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
- Richardson Maturity Model
http://martinfowler.com/articles/richardsonMaturityModel.html
- “Web API: The Good Parts”, 水野 貴明
http://www.amazon.co.jp/Web-API-The-Good-Parts/dp/4873116864

Transcript

1. 8FC
   "1*
 JO
   "OESPJE
   8PSME "VH
   UI
   
 "OESPJE
   "MM
   4UBST
   !EPUT !IZESBLFDBU
2. 8FC
   "1* Remote Procedure Call over HTTP • HTTP • JSON
3. 8FC
   "1*
   JO
   "OESPJE Remote Procedure Call over HTTP • HTTP • JSON <=> POJO • SSKDs*1 (small set of known developers) • Limited network environment 
   5IF
   GVUVSF
   PG
   "1*
   EFTJHO
   5IF
   PSDIFTUSBUJPO
   MBZFS
   IUUQUIFOFYUXFCDPNEEGVUVSFBQJEFTJHOPSDIFTUSBUJPOMBZFS
4. #BE
   8FC
   "1*
   $BO
   *OUSPEVDF • Long loading time • Complicated architecture • Bad readability in the code • Backward-incompatible changes, which would crush an old version of the app
5. (PPE
   8FC
   "1*
   JO
   "OESPJE • Hackable • Use-Case Oriented • Robust
6. )BDLBCMF
7. Anonymous Hacker by Brian Klug CC BY-NC 2.0
8. )BDLBCMF
 ͑
   *OUVJUJWF
9. 3FRVFTU
   63* GET  http://api.example.com/news/all.json GET  /news/widget/show.json?type=weather&lat=35.6&lng=139.7 GET  /news/widget/show.json?type=fortune&birthday=2015-­‐01-­‐01 • Hard to assume what kind of information returns • Query parameter can be omitted
 If so, what happens? • Inconsistent parameter names between APIs GET  /news/favorites/list.json?limit=20&max_id=183729 GET  /news/popular_articles/more.json?num=20&page=1
10. 3FRVFTU
    63* • Remove unnecessary path segments • Required parameter can be a path segment • Consistent parameter naming GET  http://api.example.com/news GET  /news/widgets/weather/35.6643109,139.719221 GET  /news/widgets/fortune/20150101 GET  /news/favorites?num=20&page=1 GET  /news/popular_articles?num=20&page=1
11. 3FRVFTU3FTQPOTF
    +40/
    #PEZ • Property Naming • Envelope • Flat vs. Hierarchical structure • Same JSON Format for POST/GET • Date
12. 1SPQFSUZ
    /BNJOH • CamelCase • snake_case • spinal-case See “Google JSON Style Guide” (http://google- styleguide.googlecode.com/svn/trunk/jsoncstyleguide.xml) 1SPQFSUZ
    /BNJOH 5XJUUFS TOBLF 'BDFCPPL TOBLF :PV5VCF DBNFM
13. DG
    (TPO
    /BNJOH
    1PMJDZ https://sites.google.com/site/gson/gson-user-guide#TOC-JSON-Field-Naming-Support • LOWER_CASE_WITH_DASHES
 e.g. “field-name” • LOWER_CASE_WITH_UNDERSCORES
 e.g. “field_name” • UPPER_CAMEL_CASE
 e.g. “FieldName” • UPPER_CAMEL_CASE_WITH_SPACES
 e.g. “Field Name” Notice! aURL " “a_u_r_l” (LOWER_CASE_WITH_UNDERSCORES)
14. &OWFMPQF {      “response”:  {          “user_profile”:  {              “name”:  “John  Doe”,              “age”:  35,              “img”:  “http://…”          }      }     } public  class  Response  {      private  UserProfileResponse  response;   }   public  class  UserProfileResponse  {      private  UserProfile  userProfile;   }   public  class  UserProfile  {      private  String  name;      private  int  age;      private  String  img;   }
15. 'MBU
    WT
    )JFSBSDIJDBM
    4USVDUVSF {        “user_name”:  “John  Doe”,        “user_age”:  35,        “user_img”:  “http://…”,        “comment”:  “This  article  is  awesome!”   } {        “user”:  {            “name”:  “John  Doe”,            “age”:  35,            “img”:  “http://…”        },        “comment”:  “This  article  is  awesome!”   }
16. 4BNF
    +40/
    'PSNBU • In most cases, better to use same JSON format for corresponding POST/GET API GET  /users/12345   {      “name”:  “John  Doe”,      “age”:  35,      “img”:  “http://…”   } POST  /users   {      “name”:  “John  Doe”,      “age”:  36,      “img”:  “http://…”   }
17. %BUF • ISO8601 is hard to parse in Android • Use Joda-Time, ThreeTenABP or another date format {      “name”:  “John  Doe”,      “age”:  35,      “img”:  “http://…”,      “last_login”:  “2015-­‐08-­‐08T11:43:09+09:00”   }
18. 1BHJOH • Offset & Limit
 api.example.com/v1/news/tech?offset=20&limit=20 • Page & Num
 api.example.com/v1/news/tech?page=2&num=20 • Token (max_id, since_id, etc.)
 api.example.com/v1/news/tech?pageToken=asdfghjkl Content might be changed
 between the API calls
19. &SSPS
    3FTQPOTF • Don’t return 2xx or 3xx if it is ERROR! • Describe why the API method failed • Better to use same JSON format across the APIs {      “errors”:  [          {              “message”:  “Invalid  argument  for  ‘num’:  ‘200’”,              “code”:  215          }      ]   }
20. 6TF$BTF
    0SJFOUFE
21. Tools by j CC BY 2.0
22. 3&45GVM
    /PU
    "MXBZT
    #FTU
23. 0OF
    4DSFFO
    0OF
    "1*
    $BMM Topic Tech Engadget My News Clip ˑ ˒ /favorites /popular_articles /channels /mynews
24. 0OF
    4DSFFO
    0OF
    "1*
    $BMM *1: API Design and Development @ APIStrat Amsterdam (https://www.youtube.com/watch?v=8BsrAblL23U) /tabs /tabs/tech Topic Tech Engadget My News Clip ˑ ˒
25. $POTJEFSBUJPOT • Performance - Cache Hit Rate - Response Time • Service Level Agreement - Server Requirement may vary • Support Devices - Android, iOS, Web
26. 0SDIFTUSBUJPO
    -BZFS The future of API design: The orchestration layer http://thenextweb.com/dd/2013/12/17/future-­‐api-­‐design-­‐orchestration-­‐layer/   The Netflix Dynamic Scripting Platform http://techblog.netflix.com/2014/03/the-­‐netflix-­‐dynamic-­‐scripting-­‐ platform.html
27. 3PCVTU
28. Broken Bulb by Brian Klug CC BY 2.0
29. 7FSTJPOJOH • Path
 api.example.com/v1/news • Request Parameter
 api.example.com/news?version=1 • Media Type
 Accept:  application/vnd.example.news+json;version=1
30. 4USBUFHJFT • Do backward-compatible changes without versioning up - New API resources - New request parameters to existing API methods - New properties to existing API response • Release new version after some backward-incompatible changes batch up • Fine grained • Switch API response based on the client request • e.g. Media Type Jump Strategy Creepy Strategy X-­‐Example-­‐App-­‐Version:  4.3.8
 Accept:  application/vnd.example.news+json;version=1
31. (SBQI2- • Language for a query to return data in a specified format • Backwards Compatible • Strongly Typed {      user(id:  3500401)  {          id,          name,          isViewerFriend,          profilePicture(size:  50)    {              uri,              width,              height          }      }   } GraphQL Introduction
 (http://facebook.github.io/react/blog/2015/05/01/graphql-introduction.html)
32. )"5&0"4  • Hypermedia as the Engine of Application State • Media Type 㱻 JSON format
 Accept:  application/vnd.example.news+json;version=1 • Client enters an application through a simple fixed URL • Other URLs are provided with API responses {      “friends”:  [          {              “name”:  “John  Doe”,              “link”:  {                  “url”:  “http://api.example.com/users/12345”,                  “rel”:  “user/detail”              }          }      ]   } *1 REST APIs must be hypertext-driven (http://roy.gbiv.com/untangled/2008/rest-apis- must-be-hypertext-driven)
33. 3FGFSFODF “Web API: The Good Parts”, ਫ໺ و໌ http://www.amazon.co.jp/Web-API-The-Good-Parts/dp/4873116864