Web API in Android World

Slide 1

Slide 1 text

8FC"1*  JO"OESPJE8PSME "VHUI   "OESPJE"MM4UBST!EPUT !IZESBLFDBU

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

#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

Slide 5

Slide 5 text

(PPE8FC"1*JO"OESPJE • Hackable • Use-Case Oriented • Robust

Slide 6

Slide 6 text

)BDLBCMF

Slide 7

Slide 7 text

Anonymous Hacker by Brian Klug CC BY-NC 2.0

Slide 8

Slide 8 text

)BDLBCMF  ͑*OUVJUJWF

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

3FRVFTU3FTQPOTF+40/#PEZ • Property Naming • Envelope • Flat vs. Hierarchical structure • Same JSON Format for POST/GET • Date

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

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)

Slide 14

Slide 14 text

&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; }

Slide 15

Slide 15 text

'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!” }

Slide 16

Slide 16 text

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://…” }

Slide 17

Slide 17 text

%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” }

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

&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 } ] }

Slide 20

Slide 20 text

6TF$BTF0SJFOUFE

Slide 21

Slide 21 text

Tools by j CC BY 2.0

Slide 22

Slide 22 text

3&45GVM/PU"MXBZT #FTU

Slide 23

Slide 23 text

0OF4DSFFO 0OF"1*$BMM Topic Tech Engadget My News Clip ˑ ˒ /favorites /popular_articles /channels /mynews

Slide 24

Slide 24 text

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 ˑ ˒

Slide 25

Slide 25 text

$POTJEFSBUJPOT • Performance - Cache Hit Rate - Response Time • Service Level Agreement - Server Requirement may vary • Support Devices - Android, iOS, Web

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

3PCVTU

Slide 28

Slide 28 text

Broken Bulb by Brian Klug CC BY 2.0

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

(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)

Slide 32

Slide 32 text

)"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)

Slide 33

Slide 33 text

3FGFSFODF “Web API: The Good Parts”, ਫ໺ و໌ http://www.amazon.co.jp/Web-API-The-Good-Parts/dp/4873116864