DESIGING URLS OF WEB APITAKAAKI MIZUNO

DESIGNING URLS OF WEB API

I hesitate to use “REST” APIs today,

so just say “JSON over HTTP”

DESIGNING URLS OF WEB API

BECAUSE I VIOLATE MANY REST PRINCIPLES WHEN I DESIGN URL OF WEB API ;(

▸ Because we cannot follow REST architecture strictly sometimes.

▸ We can use many REST concept, but sometimes choose more practical solutions.

▸ REST is really misconceived concept

▸ Roy Fielding created this word in 2000

▸ REST is the architecture that described in his article

▸ Roy Fielding also said that “I am getting frustrated by the number of people calling any HTTP-based interface a REST API.” in 2008

DESIGING URLS OF WEB APITAKAAKI MIZUNO

PRACTICAL

テキスト

SUMMARY

I will explain some basic URL design rules

DESIGNING URLS OF WEB API

NEVER INCLUDE SERVER SIDE ARCHITECTURE

▸ Good

▸ http://api.example.com/users/100

▸ Bad

▸ http://api.example.com/cgi-bin/get_user.php?user=100

DESIGNING URLS OF WEB API

YOU USE NOUN ( PLURAL FORM ) FOR URLS

▸ Good

▸ https://api.example.com/v1/companies/12345

▸ Bad

▸ https://api.example.com/v1/company/12345

▸ https://api.example.com/v1/get-companies/12345

DESIGNING URLS OF WEB API

YOU USE NOUN ( PLURAL FORM ) FOR URLS

▸ URLs “basically” points “Resource”

▸ Set of resources

▸ https://api.example.com/v1/companies

▸ Individual resource

▸ https://api.example.com/v1/companies/123

DESIGNING URLS OF WEB API

USE HTTP METHODS AS “VERBS”

GET Get data ( don’t change data )

POST Create new data & change the state of data

PUT Update data

PATCH Update a part of data

DELETE Delete data

DESIGNING URLS OF WEB API

USE ALIES LIKE “ME” OR “SELF” FOR AUTHENTICATED USER RESOURCE

▸ Use me/self for the resource for user himself/herself

▸ https://api.exmaple.com/v1/users/me

▸ https://api.exmaple.com/v1/users/1234

DESIGNING URLS OF WEB API

VERSIONING

▸ Embed Major version of “semantic versioning” into URLs.

▸ https://api.example.com/v1/users/12345

▸ Violate REST concept, but practical

▸ Other Ways

▸ Use query params

▸ https://api.example.com/users/12345?v=20161010

▸ Behavior is not clear if client calls without params

▸ Use HTTP Request headers

▸ Accept: application/vnd.example.v2+json

▸ It’s most beautiful and following HTTP concept, but not common

テキスト

VERSIONING

▸ Semantic Versioning

▸ http://semver.org/

Ver. 1. 5. 7Major Minor Patch

NEED TO HAVE BACKWARD

COMPATIBILITY

BRAKING CHANGE

DESIGNING URLS OF WEB API

SPECIFYING DATA FORMAT

▸ Use query params

▸ https://api.example.com/v1/users?format=xml

▸ Practical, easy to understand, and format is not a resource

▸ Use extension

▸ https://api.example.com/v1/users.xml

▸ Okay, but format is not a resource

▸ Use HTTP Request header

▸ Accept: application/json

▸ I like most, and it’s okay for mobile apps.

▸ But not recommend to use for public APIs.

DESIGNING URLS OF WEB API

API Design is reviewed by other developers

DESIGNING URLS OF WEB API

Cool URLs make your service more cool