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

2. The Employees Table
Field Type Description
id integer (auto-increment, Employee ID (auto-increment
primary key) column)
name varchar Employee Name
address1 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

3. The Employees API
http://api.mycompany.com/v1/

4. See all the employees
select * from employees

5. See all the employees
GET /v1/employees

6. See an Employee
select * from employees where id='123'

7. See an Employee
GET /v1/employees/123

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

9. Add an Employee: Response
"id" field is pre-populated because it is
an auto-increment column

10. Add an Employee
POST /v1/employees
Content-Type: application/json
{"name":"Hans Employee",
"address1":"123 Main Street",
"city":"Anytown", "state":"IL",
"country":"USA", "salaryband":10,
"salary":50000.0}

11. Add an Employee: Response
201 Created
Location: /v1/employees/123

12. Permanently Fire Him
delete from employees where id='123'

13. Permanently Fire Him
DELETE /v1/employees/123

14. Give Him a Raise
update employees
set salaryband=11, salary=75000.0
where id='123'

15. Give Him a Raise
POST /v1/employees/123
Content-Type: "application/json"
{"salaryband":11, "salary":75000.0}

16. Huh?
In SQL, "update" can replace any or all fields
In REST, we use PUT to replace the whole record
But that is not always possible or a good idea
In REST, we should use POST for a partial update
Some APIs use PATCH – a new HTTP verb that is not
always supported or understood

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

18. Assigning the ID Manually
PUT /v1/employees/44
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.

19. Paginate the Results
select * from employees limit 10
select * from employees offset 10 limit 10
select * from employees offset 20 limit 10

20. Paginate the Results
GET /v1/employees?limit=10
GET /v1/employees?offset=10&limit=10
GET /v1/employees?offset=20&limit=10
There is no "REST standard" for limiting result sets. We think that
"offset" and "limit" are great de facto query parameter
standards to adopt.

21. Find an Employee by Name
select * from employees
where name='Hans Employee'

22. Find an Employee by Name
GET /v1/employees?q=Hans%20Employee
"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

23. Don't Retrieve Everything
select id, salaryband, salary from employees

24. Don't Retrieve Everything
GET /v1/employees?fields=id,salaryband,salary
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.

25. Update an Employee by Name
update employees
set salaryband=5, salary=25000.0
where name like 'Hans %'
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.

26. Update an Employee by Name
GET /v1/employees?q=Hans
Look at the results and figure out the ID of the one you want...
POST /v1/employees/47
You could always have POST take parameters to allow a SQL-like
update if you wish to do this, but be careful.

27. THANKS!
Feedback?
@gbrail
gbrail@apigee.com