REST for SQL Developerswithout (too many) wordsGreg Brail          @gbrailCTO, Apigee
The Employees TableField      Type                    Descriptionid         integer (auto-increment, Employee ID (auto-inc...
The Employees APIhttp://api.mycompany.com/v1/
See all the employeesselect * from employees
See all the employeesGET /v1/employees
See an Employeeselect * from employees where id=123
See an EmployeeGET /v1/employees/123
Add an Employeeinsert into employees  (name, address1, city, state,country, salaryband, salary)values  (Hans Employee, 123...
Add an Employee: Response"id" field is pre-populated because it is  an auto-increment column
Add an EmployeePOST /v1/employeesContent-Type: application/json{"name":"Hans Employee","address1":"123 Main Street","city"...
Add an Employee: Response 201 Created Location: /v1/employees/123
Permanently Fire Himdelete from employees where id=123
Permanently Fire HimDELETE /v1/employees/123
Give Him a Raiseupdate employees  set salaryband=11, salary=75000.0  where id=123
Give Him a RaisePOST /v1/employees/123Content-Type: "application/json"{"salaryband":11, "salary":75000.0}
Huh?In SQL, "update" can replace any or all fieldsIn REST, we use PUT to replace the whole record  But that is not always p...
Assigning the ID Manuallyinsert into employees  (id, name, address1, city, state,country, salaryband, salary)values  (444,...
Assigning the ID Manually     PUT /v1/employees/44In REST, we use POST to create a new resource when   the system assigns ...
Paginate the Resultsselect * from employees limit 10select * from employees offset 10 limit 10select * from employees offs...
Paginate the Results      GET /v1/employees?limit=10      GET /v1/employees?offset=10&limit=10      GET /v1/employees?offs...
Find an Employee by Name select * from employees   where name=Hans Employee
Find an Employee by Name      GET /v1/employees?q=Hans%20Employee"q" is often used as a "search" parameter in REST APIs wi...
Dont Retrieve Everythingselect id, salaryband, salary from employees
Dont Retrieve Everything GET /v1/employees?fields=id,salaryband,salaryThere is no "REST standard" for using a "partial res...
Update an Employee by Name      update employees         set salaryband=5, salary=25000.0         where name like Hans %Up...
Update an Employee by Name      GET /v1/employees?q=HansLook at the results and figure out the ID of the one you want...   ...
THANKS!Feedback?@gbrailgbrail@apigee.com
Upcoming SlideShare
Loading in...5
×

REST API Design for SQL developers

28,830

Published on

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

Published in: Technology
0 Comments
8 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
28,830
On Slideshare
0
From Embeds
0
Number of Embeds
4
Actions
Shares
0
Downloads
126
Comments
0
Likes
8
Embeds 0
No embeds

No notes for slide

REST API Design for SQL developers

  1. 1. REST for SQL Developerswithout (too many) wordsGreg Brail @gbrailCTO, Apigee
  2. 2. The Employees TableField Type Descriptionid integer (auto-increment, Employee ID (auto-increment primary key) column)name varchar Employee Nameaddress1 varchar First line of addressaddress2 varchar Second line of addresscity varchar Employee Citystate varchar Employee Statepostal varchar Employee ZIP codecountry varchar Employee countrysalaryband integer Salary bandsalary decimal Salary, in dollars
  3. 3. The Employees APIhttp://api.mycompany.com/v1/
  4. 4. See all the employeesselect * from employees
  5. 5. See all the employeesGET /v1/employees
  6. 6. See an Employeeselect * from employees where id=123
  7. 7. See an EmployeeGET /v1/employees/123
  8. 8. Add an Employeeinsert into employees (name, address1, city, state,country, salaryband, salary)values (Hans Employee, 123 Main Street,Anytown, IL, USA, 10, 50000.0)
  9. 9. Add an Employee: Response"id" field is pre-populated because it is an auto-increment column
  10. 10. Add an EmployeePOST /v1/employeesContent-Type: application/json{"name":"Hans Employee","address1":"123 Main Street","city":"Anytown", "state":"IL","country":"USA", "salaryband":10,"salary":50000.0}
  11. 11. Add an Employee: Response 201 Created Location: /v1/employees/123
  12. 12. Permanently Fire Himdelete from employees where id=123
  13. 13. Permanently Fire HimDELETE /v1/employees/123
  14. 14. Give Him a Raiseupdate employees set salaryband=11, salary=75000.0 where id=123
  15. 15. Give Him a RaisePOST /v1/employees/123Content-Type: "application/json"{"salaryband":11, "salary":75000.0}
  16. 16. Huh?In SQL, "update" can replace any or all fieldsIn REST, we use PUT to replace the whole record But that is not always possible or a good ideaIn 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. 17. Assigning the ID Manuallyinsert into employees (id, name, address1, city, state,country, salaryband, salary)values (444, Hans Employee, 123 MainStreet,Anytown, IL, USA, 10,50000.0)
  18. 18. Assigning the ID Manually PUT /v1/employees/44In 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. 19. Paginate the Resultsselect * from employees limit 10select * from employees offset 10 limit 10select * from employees offset 20 limit 10
  20. 20. Paginate the Results GET /v1/employees?limit=10 GET /v1/employees?offset=10&limit=10 GET /v1/employees?offset=20&limit=10There is no "REST standard" for limiting result sets. We think that "offset" and "limit" are great de facto query parameter standards to adopt.
  21. 21. Find an Employee by Name select * from employees where name=Hans Employee
  22. 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 youd like: "salaryband=10", "state=IL", and so on
  23. 23. Dont Retrieve Everythingselect id, salaryband, salary from employees
  24. 24. Dont Retrieve Everything GET /v1/employees?fields=id,salaryband,salaryThere 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. 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. 26. Update an Employee by Name GET /v1/employees?q=HansLook at the results and figure out the ID of the one you want... POST /v1/employees/47You could always have POST take parameters to allow a SQL-like update if you wish to do this, but be careful.
  27. 27. THANKS!Feedback?@gbrailgbrail@apigee.com
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×