Designing api for mobile apps

agenda

motivation

about us

teammates @ polidea

experience

• Flow - Gradle based mobile build system
• RoboSpock - Android Unit testing framework
• Rooms booking system
• Company contacts apps
• Company approval process
• uTest - in-the-wild testing

A word about rest

• Definitely a buzzword
• Service design pattern, close to HTTP 1.1
• Guidelines for services layout

back to the roots

the "re" in rest

stands for representational

updating resources

• Creation: POST
• Modifications: PUT, PATCH (RFC5789)

why isn't it perfect for mobile?

Meet new limitations

throughput and latency

Connection speed market share

updating app takes long

Average submission time:

• Android - few minutes
• iOS - few days
• Windows Phone - few days

How often user updates app?

language and tools are very limited

JAVA

• Create an Executor instance
• Implement Runnable interface for every task
• Execute all tasks (synchronization?)
• Render view
• Exception handling? Tiresome..

Groovy

def result = ""

def threads = (1..3).collect {
  Thread.start {result += new URL("https://google.com").text}
}

threads*.join()
println result

Lower processing power

Patterns (lessons learnt)

what types of apps do we discuss?

http methods

using actions in paths

thinner client, more control

hateoas

            {
"users" : [
  {
    "id": 1234,
    "name": "Bob",
    "roles": [
      {"href": "http://api.example.com/roles/1"},
      {"href": "http://api.example.com/roles/2"},
      {"href": "http://api.example.com/roles/3"}
    ],
  }
]

}
        

embedded relates

{
"users" : [
  {
    "id": 1234,
    "name": "Bob",
    "roles": [
      {"name": "ADMIN"},
      {"name": "OPERATOR"},
      {"name": "USER"}
    ],
  }
]

}

multiple calls from mobile

Paging

• Should be big enough not to require to many connections
• Should let the client minimize the risk of loosing data

http cache

• iOS (AfNetworking + NSURLCache)
• Android (Retrofit + OkHttp + HttpResponseCache)

minimizing data size

example

{
    "appKey": null,
    "applicationFeatures": [
        "TM_HTML_COMPLETE",
        "ACCESS_SPUTNIK_IM_APPLICATION",
        "APPHANCE_INTEGRATION",
        "TM_TOP_TESTERS",
        "VOLTRON_DASHBOARD"
    ],
    "authDate": 1396788850862,
    "chatUUID": "1234567890",
    "code": "4c4712a4141d261ec0ca8f90379506854c4712a4141d261ec0ca8f90379506854c4712a4141d261ec0ca8f90379506854c4712a4141d261ec0ca8f9037950685",
    "grantedAuthorities": [
        "PERMISSION_BUG_PAYOUT_VIEW",
        "PERMISSION_PROJECT_VIEW",
        "PERMISSION_TESTER_PAYMENTS_VIEW",
        "PERMISSION_USER_ACCOUNT_VIEW",
        "PERMISSION_REVIEW_PAYOUT_VIEW",
        "PERMISSION_TEST_CYCLE_VIEW",
        "PERMISSION_USER_ACCOUNT_CLOSE",
        "PERMISSION_USER_ACCOUNT_EDIT",
        "PERMISSION_BUGS_AND_TEST_CASES_VIEW",
        "PERMISSION_BUG_EDIT",
        "PERMISSION_TEST_CYCLE_REVIEW_READ",
        "PERMISSION_PRODUCT_VIEW",
        "PERMISSION_BUG_CLIPBOARD_COPY",
        "PERMISSION_REQUESTED_INFO_SEND",
        "PERMISSION_TEST_RUN_TEST_CASE_SELF_ASSIGN",
        "PERMISSION_BUG_DISCARD",
        "PERMISSION_BUG_DISPUTE",
        "PERMISSION_USABILITY_SURVEY_RESPONSE_VIEW",
        "PERMISSION_USABILITY_SURVEY_RESPONSE_DISCARD",
        "PERMISSION_USABILITY_SURVEY_RESPONSE_EDIT",
        "PERMISSION_USABILITY_SURVEY_RESPONSE_CREATE",
        "PERMISSION_TEST_CYCLE_COVERAGE_VIEW",
        "PERMISSION_TEST_RUN_ASSIGNMENT_EXECUTE",
        "PERMISSION_TEST_CYCLE_PRODUCT_DESCRIPTION_VIEW",
        "PERMISSION_TEST_CYCLE_OBJECTIVES_VIEW",
        "PERMISSION_BUG_CREATE",
        "PERMISSION_TEST_CASE_TAB_VIEW",
        "PERMISSION_TEST_CYCLE_REVIEW_CREATE",
        "PERMISSION_TEST_RUN_RESULT_ATTACHMENT_UPLOAD",
        "PERMISSION_USABILITY_SURVEY_RESPONSE_PAYOUT_EDIT",
        "PERMISSION_BUG_FIX_WORTHINESS_PRICE_VIEW",
        "PERMISSION_TEST_CYCLE_REVIEW_EDIT",
        "PERMISSION_USABILITY_SURVEY_RESPONSE_PAYOUT_VIEW",
        "PERMISSION_TEST_CYCLE_REVIEW_DISCARD",
        "PERMISSION_TEST_CASE_PAYOUT_VIEW",
        "PERMISSION_TEST_CYCLE_REVIEW_MESSAGE_CREATE",
        "DATA_GRID_TESTER_VIEW",
        "PERMISSION_USABILITY_SURVEY_PAYOUT_VIEW"
    ],
    "impsersonatedUserId": null,
    "ipAddress": "127.0.0.1",
    "roles": [
        3
    ],
    "token": "43v4j3gv4jh3n23z896b2c32xbfekszb3",
    "userId": 1234,
    "userName": "frank@sinatra.com"
}

Data format

fields subsets

compression

Overall: 1,9% of initial size!

versioning

3 schools of versioning

path parameter

http://api.example.com/v1

media type (or custom header)

application/vnd.example.com.v1+json

subdomain

http://v1.api.example.com

documenting services

case study - utest app

joining responses

Reduced:

• 36 to 20 endpoints
• 86 to 20 calls (visiting all screens once)
• parallel requests

video

middleware