rest api design for sql developers

27
REST for SQL Developers without (too many) words Greg Brail @gbrail CTO, Apigee

Upload: apigee

Post on 15-Jan-2015

28.474 views

Category:

Technology


1 download

DESCRIPTION

RESTful API design principles for SQL programmers and API developers - by @gbrail, CTO apigee

TRANSCRIPT

Page 1: REST API Design for SQL developers

REST for SQL Developers

without (too many) words

Greg Brail @gbrailCTO, Apigee

Page 2: REST API Design for SQL developers

Field Type Description

id integer (auto-increment, primary key)

Employee ID (auto-increment column)

name varchar Employee Nameaddress1 varchar First line of address

address2 varchar Second line of address

city varchar Employee City

state varchar Employee State

postal varchar Employee ZIP code

country varchar Employee country

salaryband integer Salary band

salary decimal Salary, in dollars

The Employees Table

Page 3: REST API Design for SQL developers

The Employees API

http://api.mycompany.com/v1/

Page 4: REST API Design for SQL developers

See all the employees

select * from employees

Page 5: REST API Design for SQL developers

See all the employees

GET /v1/employees

Page 6: REST API Design for SQL developers

See an Employee

select * from employees where id='123'

Page 7: REST API Design for SQL developers

See an Employee

GET /v1/employees/123

Page 9: REST API Design for SQL developers

Add an Employee: Response

"id" field is pre-populated because it is an auto-increment column

Page 11: REST API Design for SQL developers

Add an Employee: Response

201 CreatedLocation: /v1/employees/123

Page 12: REST API Design for SQL developers

Permanently Fire Him

delete from employees where id='123'

Page 13: REST API Design for SQL developers

Permanently Fire Him

DELETE /v1/employees/123

Page 16: REST API Design for SQL developers

Huh?

In SQL, "update" can replace any or all fields

In REST, we use PUT to replace the whole recordBut that is not always possible or a good idea

In REST, we should use POST for a partial updateSome APIs use PATCH – a new HTTP verb that is not always supported or understood

Page 18: REST API Design for SQL developers

Assigning the ID Manually

In REST, we use POST to create a new resource when the system assigns the name. We use PUT to either replace the whole thing or create a brand-new resource when we know the name.

PUT /v1/employees/44

Page 19: REST API Design for SQL developers

Paginate the Results

select * from employees limit 10select * from employees offset 10 limit 10select * from employees offset 20 limit 10

Page 20: REST API Design for SQL developers

Paginate the Results

There is no "REST standard" for limiting result sets. We think that "offset" and "limit" are great de facto query parameter standards to adopt.

GET /v1/employees?limit=10GET /v1/employees?offset=10&limit=10GET /v1/employees?offset=20&limit=10

Page 21: REST API Design for SQL developers

Find an Employee by Name

select * from employees where name='Hans Employee'

Page 22: REST API Design for SQL developers

Find an Employee by Name

"q" is often used as a "search" parameter in REST APIs with various kinds of search expressions. You can support different parameters if you'd like: "salaryband=10", "state=IL", and so on

GET /v1/employees?q=Hans%20Employee

Page 23: REST API Design for SQL developers

Don't Retrieve Everything

select id, salaryband, salary from employees

Page 24: REST API Design for SQL developers

Don't Retrieve Everything

There is no "REST standard" for using a "partial response" to return only certain fields. We think that for simple response documents having a "fields" parameter makes a lot of sense.

GET /v1/employees?fields=id,salaryband,salary

Page 25: REST API Design for SQL developers

Update an Employee by Name

Upside of SQL – you can do stuff like this easily. Downside – if you have multiple employees named "Hans" then you probably just demoted some of them.

update employees set salaryband=5, salary=25000.0 where name like 'Hans %'

Page 26: REST API Design for SQL developers

Update an Employee by Name

You could always have POST take parameters to allow a SQL-like update if you wish to do this, but be careful.

POST /v1/employees/47

GET /v1/employees?q=Hans

Look at the results and figure out the ID of the one you want...

Page 27: REST API Design for SQL developers

THANKS!

Feedback?@[email protected]