Workshop

Learn How To Design and Document

an API

with

Workshop takeaways

How to get from the initial API project idea...

...to an API contract and its published documentation

Who are we?

Jonathan@j_michaux

product manager @ Restlet

Antoine@richard_antoine

product manager @ Restlet

RestletHelping agile teams deliver API projects

Workshop steps

1. Things to think about before you start

2. Create your API contract

3. Document and share your API

API DesignWhat to think about before you start crafting your API contract

● 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

Is the API worth building?

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

Ride Sharing API

How will the API be used?

APPUSER EXPERIENCE APIDEVELOPER

EXPERIENCE

Screenshot from BlaBlaCar

What API project methodology to use?

API Contract

Restlet Studio: API Design made easy

studio.restlet.com

Steps

1. resources

2. operations

3. responses

RFC 2616 (june 1999)

Identify resourcesWhat’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)

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”

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?

/rides- GET- POST

/rides/{id}- GET- PUT- DELETE

Define responses

● Status code

● Representation

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

Define representation

● Data structure

● Formats

Define representation: formats

JSON

XML

YAML

JPGSVG

CSV

TEXT

PDF

MPEG

ZIP

Iterate on API Design

Document your API

Prepare documentation

● Add general information: endpoints, security, a picture

● Structure your API via sections

● Complete documentation with additional information on error handling and authentication

Publish your documentation

Move forward in your API project

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

Thanks for watching!

Thanks for participating!

Try studio.restlet.com and send us feedback!