One of the greatest challenges to developing an API is ensuring that your API lasts. After all, you don’t want to have to release and manage multiple versions of your API just because you weren’t expecting users to use it a certain way, or because you didn’t anticipate far enough down the roadmap. In this session, we’ll talk about the challenge of API Longevity, as well as ways to increase your API lifecycle including having a proper mindset, careful design, agile user experience and prototyping, best design practices including hypermedia, and the challenge of maintaining persistence.

1. Building Your API for
Longevity
May 2016

2. This talk is not about how to code your API, but rather to
show you what steps and best practices you need to utilize
to build a successful, long-lived API to the extent that we
can in 45 minutes.
Disclaimer

3. • API Fanatic
• Open Source Contributor
• Author, Speaker, Consultant
• 10+ years hacking Professional Code
• Dev Relations Manager at MuleSoft
About Me

4. APIs are changing the world.

5. Over 13,000 PUBLIC APIs

7. Today APIs are connecting…

8. PHONES

9. WATCHES

10. GLASSES

11. CARS

12. REFRIGERATORS

13. THERMOSTATS

14. IN HOME
ROBOTS

15. AND MORE

16. THINK ABOUT
THAT…

17. In order to work, the IoT
requires that APIs remain
persistent.

19. Versioning and making
changes is expensive…

20. FOR EVERYONE.

21. Thankfully with 5 Simple
Steps you can build an
API that is designed to
last.

22. 1 – Go in with a long-term mindset
2 – Understand what you’re building
3 – Utilize Spec Driven Development
4 – Incorporate Best Practices
5 – Repeat steps 1-4 for all new features
They are:

23. • Your API is a Contract
• Versioning is not a solution
• Understand you suck at design
• You can pay a little now, or much more later
• You need to think things through
• Mind-set is everything
Think long-term:

24. Your API is a contract, it’s your word to your
users. Users who are not only depending on
a working API to integrate with your service,
but in order to provide food for their families.
Your users are depending on you…

25. This means you need to think through every
aspect of your API before building it.

26. • Who is your API for?
• What type of API are you building?
• How are you going to maintain your API?
• How are you going to document your API?
• How are you going to let users interact with your API?
• How are you going to manage authentication, provisioning, throttling, and developer
security?
• How are you going to protect your servers against attacks, developer misuse, etc?
• How are you going to manage support?
Thinking things through…

27. • Who are your end users?
- Current customers
- Business partners
- Third-party services
• What actions do they need access to?
- This means sitting down and talking to them!
• How can you involve them in the design process?
- Your users should be involved from Day One.
Who will be using your API?

28. • List out WHY you are making the API
- Saying that you’re exposing your data to users is not good
enough- explain HOW they will use it
• Explain how your API will interact with existing services
• List out the actions the API needs to be able to handle
- Users: add, edit, reset password, delete, etc…
- Messages: draft, send, retrieve, archive, etc…
• Do only what is NECESSARY
• DON’T get fancy.
What is the purpose of your API?

29. List out what your users need to be
able to do:

30. • Are you building a REST, partial REST, SOAP, or RPC based
API?
• Why are you building your API in that format?
• What does that mean for development?
• What does that mean for usability?
• What does that mean for longevity?
What type of API are you building?

31. What type of API are you building?

32. • Client-Server
• Stateless
• Cacheable
• Interface/ Uniform Contract
• Layered System
• Code on Demand (optional)
Do you understand the REST
constraints?

33. Most APIs are NOT
RESTful.

34. This is why it’s so important to understand
the different types of APIs, why each type
is different, and why you are choosing one
over the other.

35. It also means building your API for
beyond today…

36. ...people are fairly good at short-
term design, and usually awful at long-
term design.”
“
-Dr. Roy Fielding

37. Versioning is a necessary evil.

38. • Backwards incompatibilities
• Multiple Services to Maintain
• Multiple Systems to Support
• Creates confusion among developers
• Developer adoption is nearly impossible
Problems with versioning

39. • Backwards incompatible platform changes
• Your API is no longer extendable
• Your spec is out dated (ie SOAP)
You need to version when:

40. • Added new endpoints
• Added additional data in response
• Changed technologies (java to ruby)
• Changed your application’s services (code)
But you shouldn’t version just because you:

41. Versioning does not excuse poor
design.

42. And a poorly designed API will cost you far more in
the long run, adding months to fix what could have
been prevented in weeks. There are no shortcuts
or quick fixes, you can either build your API the
right way to begin with, or pay substantially for it in
the long-run.

43. • Define your API before Coding
• Use Design Patterns/ Code Reuse
• Mock and get User Feedback
• Make Necessary Changes
• Start Coding – to the Spec
• DO NOT DEVIATE!
Use Spec Driven Development

44. Spec Driven Development means a hybrid between
agile and waterfall methodologies. You should
develop your spec iteratively, incorporating agile user
testing. However, the actual development (coding) of
your API should be static, driven by the spec with no
deviation.

45. Disclaimer: Waterfall refers to the spec and
changing the spec only! You should still use
sprints for code development – just at this
point the spec should not be changing.

46. Hybrid approach
Design Development
Continuous, fluid, changeable Static… No turns

47. The agile design cycle

48. The goal is that by utilizing agile user testing,
carefully designing, and prototyping your API in an
iterative state, that most design related issues have
already been discovered and resolved. Allowing
you to develop fearlessly.

49. The problem is up until now, designing and
prototyping an API has been extremely costly.
Requiring developers to create a mock API
through extensive coding, and without any real
constraints/ pattern reuse.

50. However, there are several new specs being
driven by today’s industry leaders making it
easier define your API: with tools to design,
prototype, document, and allow user
interaction.

51. • RAML
• IO Docs
• Swagger
• API Blueprint
Some of today’s specs:

52. • You can define your API in just a few lines of code
• You can see what it would look like as you go
• You can quickly prototype it for devs to try
• You can quickly make tweaks/ changes
• You can easily document your API
• You can let developers try your API online
• You can let developers interact with your and other APIs
• Generate SDKs/ client libraries for your API (REST United, APIMatic.io)
Using RAML you can:

53. • You can use data models and design patterns
• You can reuse code (libraries, overlays, traits, resourceTypes)
More importantly…
resourceTypes:
- collection:
description: Collection of available <<resourcePathName>> in Jukebox.
get:
description: Get a list of <<resourcePathName>>.
responses:
200:
body:
application/json:
example: |
<<exampleCollection>>

54. The RAML API Designer

55. What does RAML look like?
#%RAML 1.0
title: World Music API
baseUri: http://example.api.com/{version}
version: v1
/playlists:
get:
responses:
200:
body:
application/json:
example: |
{
“playlistID” : 1,
“playlistName” : “My Awesome Playlist”,
“genre” : “top40”,
“songs” : 40
}

56. Remember, your spec is not a one-and-done,
rather it is the blueprint for your API. Anytime
you do something to your API you should be
modifying the spec and going through user
testing before writing code. You should never
have code that does something not defined by
your spec.

57. • Use Nouns
• Use CRUD
• Use Hypermedia (HATEOAS)
• Use Accept/ Content-Type
• Return Header Codes
• Return Descriptive Error Messages
Incorporate Best Practices:

58. Use Nouns.

59. Use:
/users
Not:
/createUser
/getUser
/deleteUser

60. Utilize CRUD.

61. Create (POST)
Read (GET)
Update (PUT/ PATCH)
Delete (DELETE)

62. Use Hypermedia.
HATEOAS

63. • HAL
• JSON-LD
• JSON API
• Collection+JSON
• Siren
Most popular hypertext link specs

64. {
"data" : {
"user": {
"userId” : 1,
"fname":"first",
"lname":"last”,
"_links" : {
"self": {
"href" : "/api/user/id/1"
},
"messages": {
"href" : "/api/message/id/1/lname/last"
}
}
}
}
}
HAL

65. Use Accept/ Content-Type
Headers.

66. Using headers gives you flexibility to support multiple types of formats
from the same resource without worrying about breaking backwards
compatibility.
Most common:
• application/json - wider language support
• application/xml
Use accept/ content-type headers

67. Use Response Codes.

68. • 200 – OK
• 201 – Created
• 304 – Not modified
• 400 – Bad Request
• 401 – Not Authorized
• 403 – Forbidden
• 404 – Page/ Resource Not Found
• 405 – Method Not Allowed
• 415 – Unsupported Media Type
• 500 – Internal Server Error

69. • 418 – I’m a Teapot…
• 420 – Enhance Your Calm
Or if you’re feeling super creative…

70. Use Descriptive Error Messages.

71. {
'exception' {
'code' : 'e3526',
'message' : 'Missing UserID',
'description' : 'A UserID is required to edit a user.',
'link' : 'http://docs.mysite.com/errors/e3526/'
}
}
The more information you provide, the easier it will be for
developers to integrate your API without contacting Support.

72. • vnd.error
• Google Errors
• JSON API
Common descriptive error formats

73. Also be sure to keep your documentation up to
date and simple enough for developers to quickly
find and implement solutions to even the most
complex problems. Poor documentation has
been the death of many an API.

74. Finally, when adding new things to
your API, be sure to:

75. 1 – Go in with a long-term mindset
2 – Understand what you’re building
3 – Utilize Spec Driven Development
4 – Incorporate Best Practices
Finally, when adding new things to
your API, be sure to:

76. It only takes ONE little thing to significantly reduce
your API’s life span. Every action you make on
your API must be carefully thought out and tested
BEFORE being pushed to production.

77. Remember...

78. Building an API is easy.

79. Designing an API is hard.

80. read more @
mulesoft.com/restbook