$30 off During Our Annual Pro Sale. View Details »

Web API in Android World

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

Hiroshi Kurokawa

August 08, 2015
Tweet

More Decks by Hiroshi Kurokawa

Other Decks in Technology

Transcript

  1. 8FC"1*JO"OESPJE Remote Procedure Call over HTTP • HTTP • JSON

    <=> POJO • SSKDs*1 (small set of known developers) • Limited network environment 5IFGVUVSFPG"1*EFTJHO5IFPSDIFTUSBUJPOMBZFS IUUQUIFOFYUXFCDPNEEGVUVSFBQJEFTJHOPSDIFTUSBUJPOMBZFS
  2. #BE8FC"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
  3. 3FRVFTU63* 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
  4. 3FRVFTU63* • 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
  5. 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
  6. DG(TPO/BNJOH1PMJDZ 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)
  7. &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;   }
  8. 'MBUWT)JFSBSDIJDBM4USVDUVSF {        “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!”   }
  9. 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://…”   }
  10. %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”   }
  11. 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
  12. &SSPS3FTQPOTF • 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          }      ]   }
  13. 0OF4DSFFO 0OF"1*$BMM Topic Tech Engadget My News Clip ˑ ˒

    /favorites /popular_articles /channels /mynews
  14. 0OF4DSFFO 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 ˑ ˒
  15. $POTJEFSBUJPOT • Performance - Cache Hit Rate - Response Time

    • Service Level Agreement - Server Requirement may vary • Support Devices - Android, iOS, Web
  16. 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
  17. 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
  18. (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)
  19. )"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)