Some REST API Best Practice Questions

[KootVanHeerden]

Hi all

I am busy building a new REST API and I'm trying to stick to standards all the way.  I read the documentation on best practices on Apigee, and designed my API based on the suggestions from that.  I use GET's for retrieving data, POST's to create new, PUT's for updates and DELETE's for, well, deletes.  Thing is this - I want to send all data and parameters across to the API using JSON (for GET, POST, UPDATE and DELETE) for consistency sake, and also because there are often quite a few parameters I want to send along.  Problem is, it is strictly not correct to send data in a GET call the same way as you would for a POST.

Sorry if this sounds confusing.  I am wondering though if there is someone out there with some experience in this, and I would greatly appreciate to hear your views on this.  For what it's worth, I'm using RESTlet in JAVA EE for my API.


Thanks!

[Steve Klabnik]

Yes, according to the spec, GET with a body doesn't mean anything.
Well, it does, but it can't be useful.

I'm not sure why you're 'sending data' when trying to request data?
What would you be sending in this JSON?

[KootVanHeerden]

Hi Steve

Thanks for your response.

The type of data I would want to send along in a GET would be like the following example when retrieving a list of users:

{
    "sid": "as4ads68ds468486essf879g8de9sdg",
    "details": {
        "company_id": 1,
        "sections": "details-all|settings-all|priv_profile-basic|access_profiles-basic|user_groups-basic",
        "offset": 0,
        "limit": 20,
        "since_id": 0,
        "filter_by": "details.surname",
        "filter": "^[aA]",
        "order_by": "details.surname",
        "order": "asc"
    }
}

I guess I could send this as something like the following (may need to URI Encode the string first, but just an example):

http://my.url.com/users?sid=as4ads68ds468486essf879g8de9sdg&company_id=1&sections=details-all|settings-all|priv_profile-basic|access_profiles-basic|user_groups-basic&offset=0&limit=20&since_id=0&filter_by=details.surname&filter=^[aA]&order_by=details.surname&order=asc

If you think about it, sending the parameters along in the URI is kind of a way of sending data to request data too.  I understand though that this would be the more correct way of doing it.

I guess my biggest question is, is it ok to do your GETs and DELETEs like this (with the URI parameters) and then send JSON for POSTs and UPDATEs?  Is that the industry accepted norm and standard way of doing a REST API which uses JSON as its primary format for sending around data?


Thanks again for the help and guidance!


Koot

[Steve Klabnik]

Sending data with a GET/DELETE is not the standard way of doing things, no.

[KootVanHeerden]

Thanks.  :)

So, would the correct thing to do for GET and DELETE then be to "sweep it behind the ?" as suggested in the Web API standards document on APIGEE?  And for POST and UPDATE sending the data via JSON would be correct?

[Steve Klabnik]

Even a DELETE with query parameters would seem a little strange to me,
but isn't exactly wrong. But yes on both counts.

> for POST and UPDATE sending the data via JSON would be correct?

Sending the data as whatever MIME type you prefer would be correct.
application/json is a fine choice.

[Michael Peterman]

The fields you listed look like query parameters to me so I think the right thing is to put them in the URL. Why? Well caching a GET request like that is normally done using the origin URL if you craft your response differently based on something other than the URL an intermediate cache could serve the wrong data.

Michael.

[KootVanHeerden]

So, is something like this the best way to go:


POST

http://my.url.com/users
data: json_code_goes_here

GET

http://my.url.com/users/123?sections=details-all,settings-all,priv_profile-basic  <--For a specific user

http://my.url.com/users/?sections=details-all,settings-all,priv_profile-basic&offset=0&limit=20  <--For a listing of users

UPDATE

http://my.url.com/users/123
data: json_code_goes_here

DELETE

http://my.url.com/users/123

Would that be the proper way of going about it?

Thanks again for all the inputs.

[Mike Schinkel]

On Oct 23, 2012, at 3:54 AM, KootVanHeerden <ko...@beyondwireless.co.za> wrote:

So, is something like this the best way to go:

POST

http://my.url.com/users
data: json_code_goes_here


GET

http://my.url.com/users/123?sectionsÞtails-all,settings-all,priv_profile-basic  <--For a specific user

http://my.url.com/users/?sectionsÞtails-all,settings-all,priv_profile-basic&offset=0&limit  <--For a listing of users


UPDATE

http://my.url.com/users/123
data: json_code_goes_here


DELETE

http://my.url.com/users/123


A couple of alternatives to consider.  

1.) Instead of using application/json for post request consider using application/x-www-form-urlencoded on request for POST and PUT (not UPDATE, and also PATCH) if you data can be made simply enough.  One benefit of this approach with POST is that it's the native format for HTML <form> submissions:

POST

http://example.com/users

request: application/x-www-form-urlencoded

response status code: XXX

PUT

http://example.com/users/123

request: application/x-www-form-urlencoded

response status code: XXX

PATCH

http://example.com/users/123

request: application/x-www-form-urlencoded

response status code: XXX

2.) Consider offering a "query" resource (or whatever name you prefer) that the API client can use to create a query using POST and then the API client can GET the query 

POST

http://example.com/queries

request: application/x-www-form-urlencoded <- sections=tails-all,settings-all,priv_profile-basic

response header: -> "Location: http://example.com/queries/hgjhg34j234jhg23"

response status code: XXX

GET

http://example.com/queries/hgjhg34j234jhg23 

response: application/json -> { "name": "value", ... }

response status code: XXX

AND/OR

PUT

http://example.com/queries/tails-settings-basic

request: application/x-www-form-urlencoded <- sections=tails-all,settings-all,priv_profile-basic

response status code: XXX

GET

http://example.com/queries/tails-settings-basic

response: application/json -> { "name": "value", ... }

response status code: XXX

Again, this are just alternatives to consider.  

-Mike

[Jørn Wildt]

> 1.) Instead of using application/json for post request consider using 

application/x-www-form-urlencoded on request for POST and PUT

Just a precausion: application/x-www-form-urlencoded does not specify anything about character encodings, so the client/server has no way of agreeing on unicode vs. other formats.

You can use multipart/form-data which contains facilities for negotiating the character set, but then you probably have better tooling for JSON which defaults to UTF-8.

Please correct me someone if I am wrong (that would help me in a couple of other places ...)

/Jørn

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group, send email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.
 
 

[KootVanHeerden]

@mikeschinkel:

Sorry, I meant to say "PUT" instead of "UPDATE" - silly moment...

Thanks for the alternative suggestions.  This API will have a very restricted "audience" (if I can call it that), so for my needs and purposes I think sticking to JSON will do the trick, but I do have some other applications where your suggestions would definitely come in handy!


@Jørn Wildt

Thanks also for your inputs.  The character encodings will actually pay a big role in this API as I will have French clients, etc.  I can see by your name that you probably come across these types of special characters a lot more than some of us, haha.