This document outlines the steps to design and document an API, including: 1. Thinking about the purpose and use of the API before starting, such as the problem it solves and how it will be used. 2. Creating the API contract by identifying resources and operations, and defining responses with status codes and data formats. 3. Documenting the API by adding general information, structuring it with sections, and completing documentation about error handling and authentication. 4. Publishing the documentation and moving the API project forward.

1. Workshop
Learn How To
Design and Document
an API
with

2. Workshop takeaways
How to get from the initial API project idea...
...to an API contract and its published documentation

3. Who are we?
Jonathan
@j_michaux
product manager @ Restlet
Antoine
@richard_antoine
product manager @ Restlet

4. Restlet
Helping agile teams deliver API projects

5. Workshop steps
1. Things to think about before you start
2. Create your API contract
3. Document and share your API

6. API Design
What to think about before you start crafting your API contract

7. ● Is the API worth building?
● What problem does the API solve?
● How will the API be used?
● What API project methodology will we use?
API Design checklist

8. Is the API worth building?

10. What problem does the API solve?
People want to do car sharing
We offer a car sharing service
Developers want to integrate it
into their apps

11. Ride Sharing API

12. How will the API be used?
APP
USER
EXPERIENCE
API
DEVELOPER
EXPERIENCE

13. Screenshot from BlaBlaCar

14. What API project methodology to use?

17. API Contract

18. Restlet Studio: API Design made easy
studio.restlet.com

19. Steps
1. resources
2. operations
3. responses
RFC 2616 (june 1999)

20. Identify resources
What’s a resource?
“A network data object or service that
can be identified by a URI [...].
Resources may be available in multiple
representations (e.g. multiple
languages, data formats, size, and
resolutions) or vary in other ways.”
RFC 2616 (june 1999)

21. What’s a resource? Second attempt!
Identify resources
“A resource is anything that’s important
enough to be referenced as a thing in itself.”
Leonard Richardson & Sam Ruby
- “Restful Webservices”

22. Define operations
“Actions that can be performed on
your resources.
The most common operations are GET,
POST, PUT, PATCH and DELETE.”
What’s an operation?

23. /rides
- GET
- POST
/rides/{id}
- GET
- PUT
- DELETE

24. Define responses
● Status code
● Representation

25. Define responses: HTTP status codes
1xx Hold on
2xx Here you go
3xx Go away
4xx You f**ked up
5xx I f**ked up

26. Define representation
● Data structure
● Formats

27. Define representation: formats
JSON
XML
YAML
JPG
SVG
CSV
TEXT
PDF
MPEG
ZIP

28. Iterate on API Design

29. Document your API

30. Prepare documentation
● Add general information: endpoints, security, a picture
● Structure your API via sections
● Complete documentation with additional information
on error handling and authentication

31. Publish your documentation

32. Move forward
in your API project

33. Next steps
● Share your API design and get feedback on it
● Use Client SDK to speed up mobile app development
● Bootstrap your server code with Server Skeletons
● Export a Swagger file if you need to

34. Thanks for
watching!
Thanks for participating!
Try studio.restlet.com
and send us feedback!