How to Reachthe Highest Levelon APIs

About meI wrote my first lines of code at 12. When I turned 17, I founded my first

tech company, making an exit at 19 to follow my dream of becoming a

professional fighter. 2 years later, as a professional fighter, I had a nasty

fracture and decided to come back to the tech world.

Nowadays, I’m CEO at LinkApi, a new developer experience in API

management and Integration tools as a service.

/thiagolimabr

@thiago.limabr

Client-serverA little about history

WebA little about history

SOAA little about history

“All companies aresoftware companies”

- Satya Nadella

Digital transformationAnd finally...

The API ecosystemAbout APIs

Generates 60% of its revenue through APIs

Total revenue of $650.1 million in 2018

10K third apps created by community

Generates 60% of its revenue through APIs

Generates 90% of its revenue through APIs

The API economyAbout APIs

Partnerships Open innovation Digital business

Internal integrations Mobile apps IoT

Digital TransformationRESTFul APIs

Best practices on APIs

01

23

4

The swamp of POX - Single URI and a single verb

Resources - MULTIPLE URI BASED RESOURCES AND SINGLE VERBS

HTTP Verbs

Hypermedia Controls

Developer ExperienceGlory of REST

• Independent resources in each URL

• Specific objects

• REST as a transport mechanism, without good practices.

Level 1GLORY OF APIs RESTFul

• Uses HTTP specification through methods, headers, status codes and pagination.

• Other best practices

Level 2GLORY OF APIs RESTFul

Base URL

LEVEL 2

Not recommended

http://www.test.com/dev/api

Recommended

http(s)://api.test.com

Good practices

Keep verbs out of your base URLs

LEVEL 2

Not recommended

URL mediumgameapi.com/getaccounts

Recommended

GET mediumgameapi.com/accountsPUT mediumgameapi.com/accountsPOST mediumgameapi.com/accountsDELETE mediumgameapi.com/accounts

Good practices

Content-type in header

LEVEL 2

Not recommended

GET /entities/123/payable_accounts.json

Recommended

GET /entities/123/payable_accounts HTTP/1.1Accept: application/jsonContent-Type: application/json

Good practices

Simplicity in the hierarchical structure

LEVEL 2

Not recommended /accounts/00928376/transaction/8738903/zip/6500/city/dublin/state/ca

Recommended

/accounts/00928376/transaction/8738903?zip=6500&city=dublin&state=ca

Good practices

(max 3 levels)

Use status code in the right way

LEVEL 2

Good practices

200 201 204 404 400 500

OK Created No content Not found Bad requestInternal

server error

Pagination

LEVEL 2

Recommendedhttps://api.pipedrive.com/v1/deals?offset=2&limit=100

Good practices

Specify which is the first page (0 or 1), if you're using page and pageSize.

Smart Filters

LEVEL 2

Good practices

Not recommended

Recommended

Make date ranges available on the filter.

• More complex demands like versioning, traceability and HATEOAS.

• Starts questioning about how the experience of the developer consuming your API.

• Uses worldwide developing patterns and creates objects thinking about readability.

Level 3GLORY OF APIs RESTFul

Versioning

LEVEL 3 Not recommended

//yourInstance.salesforce.com/services/data/

[ { "version" : "20.0", "label" : "Winter '11", "url" : "/services/data/v20.0" }, { "version" : "21.0", "label" : "Spring '11", "url" : "/services/data/v21.0" }, ... { "version" : "26.0", "label" : "Winter '13", "url" : "/services/data/v26.0" }]

Recommended

//api.stripe.com/v1/charges \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -H "Stripe-Version: 2019-03-14"

Good practices

Be clean and organized, providing a good experience for who is consuming.

Clean and legible objects

LEVEL 3Not recommended

GET /entities/:entity_id/receivable_accounts?per_page=15&page=3

{ "receivable_account": { "id": 1, "entity_id": 1, "status": 1, "status_name": "unreceived", "due_date": "2011-09-10", "occurred_at": null, "amount": "100.0", "ticket_amount": null, "interest_amount": null, "discount_amount": null, "nominal_amount": null, "total_amount": null, "description": "Material para escritório", "document": "897671718", "document_emission_date": "2011-08-07", "observation": "Papel para impressão.", "remind": true, "reminded_at": null, "income_tax_relevant": true, }}

Good practices

Readability may seem individual, but in practice, it’s not. The simpler an object is, the easier it is to understand it.

Track records

LEVEL 3

Recommended

{ "createdAt": 1501869101896,

"createdBy": "Thiago", "updatedAt": 1501869101896, "updatedBy": "Thiago"

}

Good practices

Use traceability patterns that allow you to understand who created or altered data.

Use always the default ISO 8601 for dates

LEVEL 3

Recommended

{ "createdAt":"2019-07-08T18:02:24.343Z"}

// Use UTC

Good practices

Date and time are chaotic. Keep up with the patterns.

Be careful with HATEOAS

LEVEL 3

GET https://api.github.com/users/codemazeblog

{ "login": "CodeMazeBlog", "id": 29179238, "avatar_url": "https://avatars0.githubusercontent.com/u/29179238?v=4", "gravatar_id": "", "url": "https://api.github.com/users/CodeMazeBlog", "html_url": "https://github.com/CodeMazeBlog", "followers_url": "https://api.github.com/users/CodeMazeBlog/followers", ...

Good practices

Hypermedia As The Engine Of Application State

• Beyond a stable and functioning API, delivers a better experience for who’s consuming your API.

• Now the challenge it’s on the details that will impact your consume and navigation.

Level 4GLORY OF APIs RESTFul

Use developer experience concepts

LEVEL 4

Good practices

User Experience

Development Principles

DX

Be careful with policies

LEVEL 4

Good practices

Use Throttling e Rate limiting.

Using that, consider the use cases, and the minimum acceptable for the consumer.

Event-driven API

LEVEL 4

Good practices

event

event

event

Dev-friendly error handling

LEVEL 4

Good practices Recommended

Request: GET https://api.twilio.com/2010-04-01/Accounts/1234/IncomingPhoneNumbers/1234Response: Status Code 404

{ "RestException": { "Code": "20404", "Message": "The requested resource /2010-04-01/Accounts/1234/IncomingPhoneNumbers/1234 was not found", "MoreInfo": "https://www.twilio.com/docs/errors/20404", "Status": "404" }}

Custom structure with detailed error and link to help.

Great documentation

LEVEL 4

Good practices

Not recommended

Recommended

Be clear and straight.

Describe resources and how to use them in arequest/response structure.

Getting Started Guide

LEVEL 4

Good practices

Onboarding is important.

Show the devs how to start.

Useful Tutorials

LEVEL 4

Good practices

Make good and simple tutorials about the most important API actions.

LEVEL 4

Good practices

SDK in multiple languages

Make it easy to use no matter the client library.

Provide a space for feedbacks

LEVEL 4

Good practices

There’s always room for improvement. Why not get feedbacks from who’s using more?

Good Release Notes and Changelogs

LEVEL 4

Good practices

Communicate to your final user what’s changing and why it’s important.

Dashboard and monitoring

LEVEL 4

Good practices

Data is crucial. Make sure you havea good monitoring tool.

LEVEL 4

Good practices

Console mode

Making testing easier is the first step to less errors.

Status page

LEVEL 4

Good practices

Your final user would like to know if your systems are offline.

Communication is key

LEVEL 4

Good practices

Keep your final users updated.

Thank you!

/thiagolimabr

@thiago.limabr