rest api design for sql developers

REST for SQL Developers

without (too many) words

Greg Brail @gbrailCTO, Apigee

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

The Employees API

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

See all the employees

select * from employees

See all the employees

GET /v1/employees

See an Employee

select * from employees where id='123'

See an Employee

GET /v1/employees/123

Add an Employee

insert into employees (name, address1, city, state, country, salaryband, salary)values ('Hans Employee', '123 Main Street', 'Anytown', 'IL', 'USA', 10, 50000.0)

Add an Employee: Response

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

Add an Employee

POST /v1/employeesContent-Type: application/json

{"name":"Hans Employee", "address1":"123 Main Street", "city":"Anytown", "state":"IL", "country":"USA", "salaryband":10, "salary":50000.0}

Add an Employee: Response

201 CreatedLocation: /v1/employees/123

Permanently Fire Him

delete from employees where id='123'

Permanently Fire Him

DELETE /v1/employees/123

Give Him a Raise

update employees set salaryband=11, salary=75000.0 where id='123'

Give Him a Raise

POST /v1/employees/123Content-Type: "application/json"

{"salaryband":11, "salary":75000.0}

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

Assigning the ID Manually

insert into employees (id, name, address1, city, state, country, salaryband, salary)values (444, 'Hans Employee', '123 Main Street','Anytown', 'IL', 'USA', 10, 50000.0)

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

Paginate the Results

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

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

Find an Employee by Name

select * from employees where name='Hans Employee'

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

Don't Retrieve Everything

select id, salaryband, salary from employees

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

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 %'

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...

THANKS!

Feedback?@gbrailgbrail@apigee.com