REST for SQL Developers without (too many) words Greg Brail @gbrail CTO, Apigee
Jan 15, 2015
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 an Employee
select * from employees where id='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?@[email protected]