REST API Design for SQL developers
-
Upload
apigee -
Category
Technology
-
view
28.479 -
download
1
description
Transcript of REST API Design for SQL developers
![Page 1: REST API Design for SQL developers](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/1.jpg)
REST for SQL Developers
without (too many) words
Greg Brail @gbrailCTO, Apigee
![Page 2: REST API Design for SQL developers](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/2.jpg)
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](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/3.jpg)
The Employees API
http://api.mycompany.com/v1/
![Page 4: REST API Design for SQL developers](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/4.jpg)
See all the employees
select * from employees
![Page 6: REST API Design for SQL developers](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/6.jpg)
See an Employee
select * from employees where id='123'
![Page 8: REST API Design for SQL developers](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/8.jpg)
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)
![Page 9: REST API Design for SQL developers](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/9.jpg)
Add an Employee: Response
"id" field is pre-populated because it is an auto-increment column
![Page 10: REST API Design for SQL developers](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/10.jpg)
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}
![Page 11: REST API Design for SQL developers](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/11.jpg)
Add an Employee: Response
201 CreatedLocation: /v1/employees/123
![Page 12: REST API Design for SQL developers](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/12.jpg)
Permanently Fire Him
delete from employees where id='123'
![Page 13: REST API Design for SQL developers](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/13.jpg)
Permanently Fire Him
DELETE /v1/employees/123
![Page 14: REST API Design for SQL developers](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/14.jpg)
Give Him a Raise
update employees set salaryband=11, salary=75000.0 where id='123'
![Page 15: REST API Design for SQL developers](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/15.jpg)
Give Him a Raise
POST /v1/employees/123Content-Type: "application/json"
{"salaryband":11, "salary":75000.0}
![Page 16: REST API Design for SQL developers](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/16.jpg)
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 17: REST API Design for SQL developers](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/17.jpg)
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)
![Page 18: REST API Design for SQL developers](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/18.jpg)
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](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/19.jpg)
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](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/20.jpg)
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](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/21.jpg)
Find an Employee by Name
select * from employees where name='Hans Employee'
![Page 22: REST API Design for SQL developers](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/22.jpg)
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](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/23.jpg)
Don't Retrieve Everything
select id, salaryband, salary from employees
![Page 24: REST API Design for SQL developers](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/24.jpg)
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](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/25.jpg)
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](https://reader034.fdocuments.net/reader034/viewer/2022051611/54b79e7f4a79590e758b45d6/html5/thumbnails/26.jpg)
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...