The document outlines three main issues with app APIs: the need for data agnosticism, proper identification and response to the app type, and the importance of sending comprehensive data. It provides examples of poor and good API design practices, emphasizing consistency and clarity in data types and structures. The author advocates for sending additional useful data and ensuring that API responses are adaptable to different devices and circumstances.

1. 3 things your app API is doing
WRONG
Robert MacLean  @rmaclean

2. Introduction
 I’m Robert
 that is all you get, I have 18 slides to get through
 Not covering the obvious (security, validate input, use REST etc…)
 Do this regardless if you plan for apps or not

3. Be agnostic
 REST won
 REST is about HTTP
 Stop pushing your C#, PHP or JavaScript views on the world
 Tip: SQLite data structures

4. Be agnostic – bad
example 1
[{
“title”: {
“en”: ”this is an awesome talk”
}
}]
[{
“title”: {
“fr”: ”Il s'agit d'un discours génial”
}
}]
Magically appearing properties.
Assumption of dynamic languages &
objects

5. Be agnostic – good
example 1 [{
“title”: {
“value”: ”this is an awesome talk”,
“lang”:”en”
}
}]Be consistent and state intent

6. Be agnostic – bad
example 2
[{
“data”: [
{
“user”:”paul smith”,
“id”:12,
“type”:”actor”
},
{
“title”:”theseus”,
“id”:232,
“type”:”game”
},
{
“delete”:1,
“id”:12,
“type”:”actor”
}]
}]
Arrays that contain different types

7. Be agnostic – good
example 2
[{
“actors”: [
{
“user”:”paul smith”,
“id”:12,
}],
“games”: [
{
“title”:”theseus”,
“id”:232,
}],
“deleted”: [
{
“id”:12,
“type”:”actor”
}]
}]
Separate arrays or totally separate
calls would be good.

8. Identify and respond
 Your API should allow the app to say what type of app it is
 Do not expect technical information
 Respond accordingly to the identity

9. Identify– bad example
[{“user”:”1234”}]
[{“user”:”1234”, “deviceId”:”76879902”}]
[{“user”:”1234”,
“deviceId”:”76879902”,”wresolution”:480,”hresolu
tion”:800}]
1. Assuming user without device
2. No device identification info
3. Asking for technical information

10. Identify – good example [{
“user”:”1234”,
“deviceId”:”76879902”,
”os”:”windows”,
”platform”:”phone”,
”resolution”:”medium”
}]
Using sets of identifiers which are not
fixed to hardware details

11. Respond – bad example
[{
“image”:{
“50x50”: “http://fqdn/image50x50.png”,
“400x400”: “http://fqdn/image400x400.png”,
}
}]
1. Fixed content regardless of device
2. Same respond data type

12. Respond – good example
[{
“image”:{
“thumbnail”: “http://fqdn/image50x50.png”,
“image”: “http://fqdn/image400x400.png”,
}
}]
<image thumbnail=“http://fqdn/image50x50.png”
image=“http://fqdn/image400x400.png” />
1. Provide data based on info
2. Different data types

13. Send more data
 Send data that isn’t shown
 Send data that has been computed already
 Send data in raw formats

14. Send more data – bad
example 1
[{
“videos”:[
“1”:”http://fqdn/video1.mp4”,
“2”:”http://fqdn/video2.mp4”,
]
}]
Out of band:
 Adverts can’t be skipped
 Advert is any clip less than 30sec
Send data that isn’t shown
Send data that has been computed
already

15. Send more data – good
example 1
[{
“videos”:[
{
“id”: “1”,
“url”: “http://fqdn/video1.mp4”,
“isAdvert”: “false”,
“hash”:”8736426348726387462123123123”
},
{
“id”: “2”,
“url”: “http://fqdn/video2.mp4”,
“isAdvert”: “true”,
“hash”:”8739487298734987329847298343”
}
]
}]
Send data that isn’t shown
Send data that has been computed
already

16. Send more data – bad
example 1
[{
“description”:”<h1>Jump by Van Halen</h1><div
class=‘artist’ id=‘1’>Van Halen</div><div
class=‘title’ id=‘9000’>Jump</div><div
class=‘content’>Jump is a song by the American
rock group Van Halen. It was released in
December 1983 as the lead single from their
album 1984. It is the only single the group
released in their career to reach number one on
the U.S. Billboard Hot 100.</div>
}]
Send the raw data

17. Send more data – good
example 1
[{
“title”:”Jump by Van Halen”,
“artist”:1,
“title”:9000,
“description”:”Jump is a song by the American
rock group Van Halen. It was released in
December 1983 as the lead single from their
album 1984. It is the only single the group
released in their career to reach number one on
the U.S. Billboard Hot 100.”
}]
Send the raw data.
Identify and respond works here too.

18. Thanks
 Be agnostic
 Identify and respond
 Send more data
@rmaclean
www.sadev.co.za