Showcasing some of the approaches Contentful used to make their API suitable for all devices - from embedded hardware to big server.

1. Adapting our API
for multiple platforms
BY ROUVEN WEßLING

2. Like a CMS… without the bad bits.
Contentful is a content management developer
platform with an API at its core.

3. How do you consume
news?
At Contentful we had to adapt our APIs
to suite a wide variety of platforms and
use cases. How did we do it?

4. In the UK newspaper
circulation fell 43%
between 2001 and 2014.
In the US 10% of
subscribers read online.
NEWSPAPER
The old fashioned way.
As of 2016, just 20% of
US adults read print
paper news. Just 5% of 18
to 29-year-olds.

5. 85% of US adults
consume news on digital
devices.
13% consume news only
on desktops/laptops.
42% of adults using both
mobile and desktop
prefer the desktop.
WEB

6. 70% of US adults aged
18-29 prefer or only use
mobile devices.
88% of mobile internet
time is spent in apps.
25% of US smartphone
owners prefer apps; 25%
the mobile web.
MOBILE
All the cool kids do it.

7. Amazon has sold over 5
million Echos in the US.
CNN got 36.5 million
unique readers from
Apple News in
September 2016.
Sky Sports gets around 1
million daily viewers on
Snapchat Discover.
NEW PLATFORMS
Are you ready for them?

8. TODAY CONTENT
HAS TO BE MULT-PLATFORM
Consumption behavior is changing.
Companies who can’t adapt will be left behind.

9. Modular
Built to make content reusable
and channel agnostic.
Microservice
API-driven design allows
powerful integration
with third parties.
Cloud service
Focus on the user experience;
not running the backend
The CMS that enables
developers to serve all platforms.

10. 10
How does that
affect our APIs?

11. Limitations
Enable developers to present content on all connected platforms.*
The devices might lose its internet
connection at any time.
Offline
Mobile devices might be on a slow or
metered connection.
Bandwidth
Some platforms require the content to
be sent to them.
Push
Embedded platforms have limited
processing power.
Performance
*As long as they support HTTP and JSON

12. 12
Offline
Mobile devices might lose their internet connection at
any time.

13. SYNC API
• Download all content to the
device
• Store a token that marks the last
content that has been synced
• Next sync; get only changed
content
#!/bin/sh
curl 'https://cdn.contentful.com/spaces/cfexampleapi/sync?
access_token=b4c0n73n7fu1&initial=true'

14. SYNC API
• Download all content to the
device
• Store a token that marks the last
content that has been synced
• Next sync; get only changed
content
{
"sys": {
"type": "Array"
},
"items": [
{
"sys": {},
"fields": {
"name": {
"en-US": "London"
},
"center": {
"en-US": {
"lon": -0.12548719999995228,
"lat": 51.508515
}
}
}
}
],
"nextSyncUrl": "https://cdn.contentful.com/spaces/cfexampleapi/sync?
sync_token=w5ZGw6JFwqZmVcKsE8Kow4grw45QdybCnV_Cg8OASMKpwo1UY8K8bsKFwqJrw7DDhcKnM2
RDOVbDt1E-wo7CnDjChMKKGsK1wrzCrBzCqMOpZAwOOcOvCcOAwqHDv0XCiMKaOcOxZA8BJUzDr8K-
wo1lNx7DnHE"
}

15. Push
Unlike the web and mobile apps, some content
platforms require the publisher to provide the content
to them.

16. www.contentful.com
WEBHOOKS
• Don’t call us; we’ll call you
• Select the events necessary
• Payload contains the entire body

17. 17
Bandwidth
Mobile networks are super fast - but not everywhere.
Enable users to get to content before they get bored.

18. Images API
• Resize images server side so they are as small as possible.
• When constrained by bandwidth, resize further or reduce the quality.

19. LOCALES
• Most people never change the
websites/apps language
• Optimize for the common case:
only load for the users current
locale
#!/bin/sh
curl 'https://cdn.contentful.com/spaces/cfexampleapi/entries/nyancat?
access_token=b4c0n73n7fu1&locale=en-US'
curl 'https://cdn.contentful.com/spaces/cfexampleapi/entries/nyancat?
access_token=b4c0n73n7fu1&locale=tlh'

20. LOCALES
• Most people never change the
websites/apps language
• Optimize for the common case:
only load for the users current
locale
{
"sys": {
"id": "nyancat",
"locale": "en-US"
},
"fields": {
"name": "Nyan Cat",
"bestFriend": {
"sys": {
"type": "Link",
"linkType": "Entry",
"id": "happycat"
}
},
"birthday": "2011-04-04T22:00:00+00:00",
"lives": 1337,
}
}

21. LOCALES
• Most people never change the
websites/apps language
• Optimize for the common case:
only load for the users current
locale
{
"sys": {
"id": "nyancat",
"locale": "tlh"
},
"fields": {
"name": "Nyan vIghro'",
"bestFriend": {
"sys": {
"type": "Link",
"linkType": "Entry",
"id": "happycat"
}
},
"birthday": "2011-04-04T22:00:00+00:00",
"lives": 1337,
}
}

22. Performance
Embedded platforms are very different from the
computer we all use.

23. ADJUST PAYLOAD
• JSON is very lightweight
• Less JSON parses faster than
more JSON
• Only worth it on severely
constrained devices
#!/bin/sh
curl 'https://cdn.contentful.com/spaces/cfexampleapi/entries?
access_token=b4c0n73n7fu1&content_type=cat&select=sys.id,fields.name'

24. ADJUST PAYLOAD
• JSON is very lightweight
• Less JSON parses faster than
more JSON
• Only worth it on severely
constrained devices
{
"sys": {
"type": "Array"
},
"total": 3,
"skip": 0,
"limit": 100,
"items": [
{
"fields": {
"name": "Nyan Cat"
},
"sys": {
"id": "nyancat"
}
},
{
"fields": {
"name": "Garfield"
},
"sys": {
"id": "garfield"
}
}
]
}

25. RESOLVE
REFERENCES
• Avoid API requests by fetching
linked resources
• Control over the level of depth
#!/bin/sh
curl 'https://cdn.contentful.com/spaces/cfexampleapi/entries?
access_token=b4c0n73n7fu1&content_type=cat&fields.color=rainbow&include=1'

26. RESOLVE
REFERENCES
• Avoid API requests by fetching
linked resources
• Control over the level of depth
{
"items": [{
"fields": {
"name": "Nyan Cat",
"color": "rainbow",
"bestFriend": {
"sys": {
"type": "Link",
"id": "happycat"
}
}
}
}],
"includes": [{
"fields": {
"name": "Happy Cat",
"color": "gray",
"bestFriend": {
"sys": {
"type": "Link",
"id": "nyancat"
}
}
}
}]
}

27. COMPLEX QUERIES
• Avoid API requests with
complex queries
• Search on referenced content
#!/bin/sh
curl ‘https://cdn.contentful.com/spaces/cfexampleapi/entries?
access_token=b4c0n73n7fu1&content_type=cat&limit=1&include=0&
fields.bestFriend.sys.contentType.sys.id=cat&fields.bestFriend.fields.color=rainbow'

28. COMPLEX QUERIES
• Avoid API requests with
complex queries
• Search on referenced content
{
"sys": {
"type": "Array"
},
"total": 1,
"skip": 0,
"limit": 1,
"items": [
{
"sys": {
"id": "happycat",
"locale": "en-US"
},
"fields": {
"name": "Happy Cat",
"color": "gray",
"bestFriend": {
"sys": {
"type": "Link",
"linkType": "Entry",
"id": "nyancat"
}
},
"lives": 1
}
}
]
}

29. ROUVEN WEßLING
Twitter: @RouvenWessling
Email: rouven@contentful.com