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.