Jono discusses practical design-led thinking approaches to creating scalable and agile server-side API’s for your mobile applications, from initial planning through to execution and documentation. While targeted at Swift as the language, you’ll be able to apply these techniques to creating API’s in almost any server-side language.

1. Creating Rich
Server API’s for
your Mobile Apps
Jonathan Guthrie
PerfectlySoft Inc.
www.perfect.org
@iamjono
Best Practices
& Guidelines

2. Meta-Themes
• authentication
• analytics
• structure
• deployment
• documentation
Creating Rich Server API’s for your Mobile Apps

3. Authentication
• Local authentication
• OAuth2
• And the others like SPENGO, LDAP
Creating Rich Server API’s for your Mobile Apps

4. Local Authentication
Creating Rich Server API’s for your Mobile Apps
{
“user”: “me”,
“pwd”: “iHeartSwift”
}
{
“token”: “qwerty123”
}
Initial interaction

5. Local Authentication
Creating Rich Server API’s for your Mobile Apps
Header:
Authorization: Bearer qwerty123
Ongoing interaction

6. OAuth2 Authentication
Creating Rich Server API’s for your Mobile Apps
Allow me please?
{“token”:“qwerty123”}
Initial interaction (simplified)
OAuth2
Provider
{“token”:“qwerty123”}
user
info

7. Authentication
Local
Creating Rich Server API’s for your Mobile Apps
Easy to implement
Control over user info
User maintains many accounts
Password Fatigue
OAuth2
Low barrier to usage
User maintains fewer accounts
Harder to implement
Almost no control over content
Hard to deactivate a user
Better in corporate
environments
Better in user-first
environments

8. Authentication
always authenticate.
Creating Rich Server API’s for your Mobile Apps
If all else fails, use “fingerprinting”
“appid”: “mygreatapp”,
“deviceid”: “somethingrandom”,
“appversion”: 1.3.6
Add to API headers:

9. Authentication
Creating Rich Server API’s for your Mobile Apps

10. Analytics
• Local logging
• Google Server API
Creating Rich Server API’s for your Mobile Apps

11. Local Logging
Creating Rich Server API’s for your Mobile Apps
All interactions contain these headers:
“appid”: “mygreatapp”,
“deviceid”: “somethingrandom”,
“appversion”: 1.3.6
Log to DB

12. Google Analytics
Creating Rich Server API’s for your Mobile Apps
All interactions contain these headers:
“appid”: “mygreatapp”,
“deviceid”: “somethingrandom”,
“appversion”: 1.3.6
Google Analytics
Measurement Protocol
https://github.com/PerfectlySoft/Perfect-GoogleAnalytics-MeasurementProtocol

13. Structure
• Simplicity is King
• Routing
• Code structure
Creating Rich Server API’s for your Mobile Apps

14. Simplicity is King
Creating Rich Server API’s for your Mobile Apps
• Minimize HTTP calls from the client
• Balance minimizing calls with
premature optimization
• Plan, and spend more time planning.

15. Routing
Creating Rich Server API’s for your Mobile Apps

16. Routing
Creating Rich Server API’s for your Mobile Apps
// Docs
routes.append([
"method":"post", "uri":"/api/v1/docs/create",
“handler":WebHandlers.docCreate
])
routes.append([
"method":"post", "uri":"/api/v1/docs/save/doc",
“handler":WebHandlers.docSaveDoc
])
routes.append([
"method":"get", "uri":"/api/v1/docs/XAR0fzvSvImUwderQSJvFg",
“handler":WebHandlers.docGet
])
API version 1

17. Routing
Creating Rich Server API’s for your Mobile Apps
// Docs
routes.append([
"method":"post", "uri":"/api/v1/docs/create",
“handler":WebHandlers.docCreate
])
routes.append([
"method":"post", "uri":"/api/v1/docs/save/doc",
“handler":WebHandlers.docSaveDoc
])
routes.append([
"method":"get", "uri":"/api/v1/docs/XAR0fzvSvImUwderQSJvFg",
“handler":WebHandlers.docGet
])
POST
GET

18. Routing: HTTP Verbs
Creating Rich Server API’s for your Mobile Apps
GET
POST
PATCH
PUT
DELETE
Retrieve resources
Create resource
Update resource
Upload resource (aka file)
Delete resource

19. Routing: HTTP Verbs
Creating Rich Server API’s for your Mobile Apps
GET
POST
PATCH
PUT
DELETE
/v1/user/{id}
/v1/user
/v1/user
/v1/user/{id}/avatar
/v1/user/{id}

20. Routing: ID’s
Creating Rich Server API’s for your Mobile Apps
// Docs
routes.append([
"method":"post", "uri":"/api/v1/docs/create",
“handler":WebHandlers.docCreate
])
routes.append([
"method":"post", "uri":"/api/v1/docs/save/doc",
“handler":WebHandlers.docSaveDoc
])
routes.append([
"method":"get", "uri":"/api/v1/docs/XAR0fzvSvImUwderQSJvFg",
“handler":WebHandlers.docGet
])
Resource ID

21. Routing: ID’s
Creating Rich Server API’s for your Mobile Apps
• Never expose integer ID’s
• Sequential ID’s are guessable
• Use [A-Za-z0-9] ID’s
• Encrypt or abstract if needed

22. Code Structure
Creating Rich Server API’s for your Mobile Apps
• Clearly organize your code structure
• Maximize code re-use
• Employ sensible functional programming

23. Clear Organization
Creating Rich Server API’s for your Mobile Apps
Use folder / groups

24. Clear Organization
Creating Rich Server API’s for your Mobile Apps
Separate handlers
into digestible and
identifiable chunks

25. Maximize code-reuse
Creating Rich Server API’s for your Mobile Apps
Every request
var context: [String : Any] = [
"accountID": contextAccountID,
"authenticated": contextAuthenticated,
"userlist?":"true",
"msg": msg,
"configTitle": configTitle,
"configLogo": configLogo,
"configLogoSrcSet": configLogoSrcSet
]

26. Maximize code-reuse
Creating Rich Server API’s for your Mobile Apps
extension WebHandlers {
static func appExtras() -> [String : Any] {
return [
"configTitle": configTitle,
"configLogo": configLogo,
"configLogoSrcSet": configLogoSrcSet
]
}
}

27. Maximize code-reuse
Creating Rich Server API’s for your Mobile Apps
var context: [String : Any] = [
"accountID": contextAccountID,
"authenticated": contextAuthenticated,
"userlist?":"true",
"msg": msg
]
// add app config vars
for i in WebHandlers.appExtras() {
context[i.0] = i.1
}

28. Sensible functional
programming
Creating Rich Server API’s for your Mobile Apps
Thursday, June 8
this.

29. Deployment
Horizontal vs vertical scaling
Creating Rich Server API’s for your Mobile Apps

30. Vertical Scaling
Creating Rich Server API’s for your Mobile Apps
bigger, better, faster, more

31. Vertical Scaling
Creating Rich Server API’s for your Mobile Apps
bigger,
better,
faster,
more $$$
aka: Single Point of Failure

32. Horizontal Scaling
Creating Rich Server API’s for your Mobile Apps
lots & lots & lots of bricks

33. Horizontal Scaling
Creating Rich Server API’s for your Mobile Apps
lots & lots & lots of bricks

34. API Documentation
Creating Rich Server API’s for your Mobile Apps
crickets, anyone?

35. API Documentation
Creating Rich Server API’s for your Mobile Apps
Be kind to your API users:
Document your API

36. API Doc Engines
Creating Rich Server API’s for your Mobile Apps
crickets, anyone?
• readme.io
• Slate
• Perfect API Doc Server
• Raw HTML

37. API Documentation
Creating Rich Server API’s for your Mobile Apps

38. API Documentation
Creating Rich Server API’s for your Mobile Apps
Document first?
or
Code first?

39. API Documentation
Creating Rich Server API’s for your Mobile Apps
Plan first

40. API Documentation
Creating Rich Server API’s for your Mobile Apps
Plan first
then document
then code, and document

41. API Documentation
Creating Rich Server API’s for your Mobile Apps
Be kind to those who come later:
Document your code

42. API Documentation
Creating Rich Server API’s for your Mobile Apps

43. Questions?
Creating Rich Server API’s for your Mobile Apps
Jono Guthrie
PerfectlySoft Inc.
www.perfect.org
@iamjono
Slack: http://www.perfect.ly