REST API Design for SQL developers

REST for SQL Developerswithout (too many) wordsGreg Brail @gbrailCTO, Apigee

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

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 Main Street,Anytown, IL, USA, 10, 50000.0)

Add an Employee: Response"id" ﬁeld 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":"Anytown", "state":"IL","country":"USA", "salaryband":10,"salary":50000.0}

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 ﬁeldsIn 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

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)

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.

Paginate the Resultsselect * from employees limit 10select * from employees offset 10 limit 10select * from employees offset 20 limit 10

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.

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 with various kinds of search expressions. You can support different parameters if youd like: "salaryband=10", "state=IL", and so on

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 response" to return only certain ﬁelds. We think that for simple response documents having a "ﬁelds" parameter makes a lot of sense.

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.

Update an Employee by Name GET /v1/employees?q=HansLook at the results and ﬁgure 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.

THANKS!Feedback?@gbrailgbrail@apigee.com

http://blog.apigee.com	13182
http://blog.sonoasystems.com	47
http://translate.googleusercontent.com	13
http://www.afterjohn.appspot.com	2
http://who1.2cn.in	1
http://ip51.216-86-157.static.steadfastdns.net	1
http://webcache.googleusercontent.com	1

REST API Design for SQL developers

by Apigee on Mar 18, 2011

Accessibility

Categories

Tags

Upload Details

Usage Rights

7 Embeds 13,247

Statistics

REST API Design for SQL developers — Presentation Transcript