This is a style question about REST API design
I have an API which returns a particular resource, and can return either the fields of the resource as a JSON object, or a PDF representation of the resource. The normal REST way of doing that is to use the same URL, but return either the JSON object or the PDF data depending on the "Accept" header of the request.
This has been fine when calling the API from a client application. But now I am writing a web application, and I want to display the PDF. I can fetch the PDF data with XMLHttpRequest, but there isn't an easy way to display it. (I recall some hack involving passing the whole base64-encoded content in the URL, but that is both flaky and disgusting).
The easy way to display a PDF in a web application is window.open(), but I can't pass an Accept header to that (there are a few questions here for people asking how to do that).
This seems like a potentially common situation. What's the best workaround? Stick ?pdf or /pdf or ?accept=pdf onto the url? Is there a de facto standard? Or is there a solution I haven't thought of (maybe treating "application/pdf" as the default request mime type, and only returning the JSON object if the Accept header is "application/json")?
Actually the more I think of it, the more that last idea (return PDF unless explicitly asked for application/json in the Accept header) seems like the right answer. A web browser can display PDFs (at least usually, these days) and not JSON objects, so a request made natively by a browser should always get the PDF, and REST clients that wants JSON data would normally explicitly ask for application/json, so the API server should not do that by default if it has a better browser-compatible form.
Since it took actually explaining this whole problem into the question box to make me think of the answer I posted the question anyway.
Related
I am currently trying to build a REST endpoint whereby an authenticated user can download a PDF. In researching the proper way to do this, I have mostly seen that JSON or XML are the proper response bodies to give. However, this site explains that the response can be something other than JSON as long as it's some human-readable document.
So, is it ever okay for a REST API to return application/pdf as the response type instead of application/json or application/xml?
Yes, definitely, a RESTful API can return whatever it wants. There is no constraint to be human-readable (although I think the linked article tries to argue exactly the opposite). Just think of the Web, which is REST-based, returning images, movies, sometimes even runnable code.
There are however some constraints. Any representation returned should be 'self-contained', meaning it has to has every piece of information necessary for the client to make sense of it. In this case, it would basically mean to just set the type 'application/pdf' properly on the response.
I am trying to stick to the Restful design pattern for both JSON and HTML. My issue is the design for creating a new resource (amongst others, but this is the gist of the issue). IE:
JSON – POST to /resource creates a new resource.
JSON – GET to /resource returns a list of resources.
JSON – GET to /resource/{id} returns a resource.
HTML – POST to /resource creates a new resource.
HTML – GET to /resource returns a list of resources.
HTML – GET to /resource/{id} returns a resource.
All good so far – but I need a HTML form to actually create the data to send to the HTML POST. Obviously POST and GET already do things. I could use one of the below to return the HTML form:
HTML – GET to /resource?CREATE
HTML - GET to /resource?action=CREATE
HTML – GET to /resources/CREATE
But they seem like a kludge and not that intuitive.
Any thoughts or ideas?
EDIT - See my answer to my question below. At present this is (I consider) the best option.
I would indeed use something like /resources/create. If you want to allow for non-numeric identifiers, then this will not work. In that case you can identify a resource with a prefix, such as /resources/resource-{id} and then you can still use /resources/create.
I found this blog post really helpful to make URI scheme decisions: http://blog.2partsmagic.com/restful-uri-design/
In fact, you should leverage content negotiation (CONNEG) when you want to handle several formats within RESTful services.
I mean:
Set the Content-Type header to specify the type of sent data
Set the Accept header to specify the type of data you want to receive
The server resources should leverage these hints to make the appropriate data conversion.
In the case of JSON, the content type would be obviously application/json. For HTML form, you should leverage the content type application/x-www-form-urlencoded (or multipart/form-data if you want to upload files as well). See the specification for more details.
Otherwise, you shouldn't use action in URL since it's not really RESTful. The HTTP verb should determine the action to do on the resource. I mean, to create a resource, the POST method should be used. The GET method aims to retrieve the state of a resource.
For more details, you could have a look at this blog post:
Designing a Web API (i.e. RESTful service).
I have an answer. I'll use standard RESTful POST from a HTML page, but when I have no form parameters sent and my accept header is text/html, I'll send a HTML form to the requestor. Keeps RESTful URI design and allows a clean HTML form + process (2 step).
HTML - POST - /resources (with no form attributes) generates a HTML form
HTML - POST - /resources (with form attributes) adds a resource
JSON - POST - /resources (with form attributes) adds a resource
OK, it's not "strictly" RESTful as I'm POSTing but not creating a new resource so in theory I should use a GET for that, but it's the best of a mismatched design.
If anyone can provide a better solution, I'm still all ears :-)
I'd rather add and endpoint called /templates/ that returns a template/form/whatever you need for given action. It also seems that the server should be unaware of such form existence. It can accept or reject a request and it's client job to submit it in an appropriate format.
I guess that you mix processing the view with preparing RESTful endpoints. The backend site should be completely unaware of the fact that some sort of view/form is required. It's client job to prepare such form.
We're having a bit of a discussion on the subject of posting data to a REST endpoint. Since the objects are quite complex, the easiest solution is to simply serialize them as JSON and send this in the request body.
Now the question is this: Is this kosher? Or should the JSON be set as a form parameter like data=[JSON]? Or is sending of JSON in the request body just frowned upon for forcing the clients using the application, to send their data via JavaScript instead of letting the browser package it up as application/x-www-form-urlencoded?
I know all three options work. But which are OK? Or at least recommended?
I'd say that both methods will work well
it's important that you stay consistent across your APIs. The option I would personally choose is simply sending the content as application/json.
POST doesn't force you to use application/x-www-form-urlencoded - it's simply something that's used a lot because it's what webbrowsers use.
There is nothing wrong about sending it directly as serialized JSON, for example google does this by default in it's volley library (which obviously is their recommended REST library for android).
If fact, there are plenty of questions on SO about how not to use JSON, but rather perform "normal" POST requests with volley. Which is a bit counter intuitive for beginners, having to overwrite it's base class' getParams() method.
But google having it's own REST library doing this by default, would be my indicator that it is OK.
You can use JSON as part of the request data as the OP had stated all three options work.
The OP needs to support JSON input as it had to support contain complex structural content. However, think of it this way... are you making a request to do something or are you just sending what is basically document data and you just happen to use the POST operation as the equivalent of create new entry.
That being the case, what you have is basically a resource endpoint with CRUDL semantics. Following up on that you're actually not limited to application/json but any type that the resource endpoint is supposed to handle.
For non-resource endpoints
I find that (specifically for JAX-RS) the application/x-www-urlencoded one is better.
Consistency with OAuth 2.0 and OpenID Connect, they use application/x-www-urlencoded.
Easier to annotate the individual fields using Swagger Annotations
Swagger provides more defaults.
Postman generates a nice form for you to fill out and makes things easier to test.
Examples of non-resource endpoints:
Authentication
Authorization
Simple Search (though I would use GET on this one)
Non-simple search where there are many criteria
Sending a message/document (though I would also consider multipart/form-data so I can pass meta data along with the content, but JAX-RS does not have a standard for this one Jersey and RestEasy have their own implementations)
According to the HTML4 reference there's no attribute to pass on HTTP headers using the anchor tag.
I would like to offer a link requesting for a specific file type using the Accept header.
The only way I can see is simply let it be, and pass a GET parameter.
You may as why I would want to do this... I intend to expose a bunch of methods as a public API, serving the results as JSON. And when doing requests using JavaScript, or another programming language, using the Accept header to request a specific response format is "The Right Way" to do it. But that would mean that I need to accommodate both the Accept header and the GET parameter in my code, which smells like a duplication of logic.
This topic is largely debatable, as such links may not be possible to bookmark in the browser... still... I'd like to know if it was possible without too much magic...
I don't see another way than using the GET parameter or an extension like
http://myurl/page?format=json
or better
http://myurl/page.json
Which overrides the accept header (since the browser will only send it's default
accept header). Then you just need to initialize a format to accept header mapping like this (which I don't find duplicate logic at all):
{
"json" : "application/json",
"html" : "text/html"
}
You can't.
I intend to expose a bunch of methods as a public API, serving the results as JSON. And when doing requests using JavaScript, or another programming language, using the Accept header to request a specific response format is "The Right Way" to do it. But that would mean that I need to accommodate both the Accept header and the GET parameter in my code, which smells like a duplication of logic.
If I understand you correctly, you don't have to do this anyway. Browsers already supply an Accept header.
Hmm, seems like if your results are JSON, you will be sending / receiving from script anyway, which can provide any header you want. Just have your link call a script function and you're done.
I have a URI for a collection of resources called 'facts', and URIs for each 'fact' resource in that collection.
The form for creating a new 'fact' should be requested with a GET, I believe, but I'm having trouble deciding what URI it should be made to.
A GET to the collection URI should return a list of the 'fact' resource URIs. Each 'fact' URI should return its contents as a response to GET. The actual 'fact' creation would be a POST (or PUT, depending on the situation), of course.
I see a few options, but none seem satisfactory:
Add a 'fact form' URI which the 'facts' URI will reference. A GET to this URI gives the HTML form. Seems wrong to have another resource just for a description of a resource.
A POST made to the 'facts' URI without including any form data in the headers would return the form. Then after the user fills the form in, it would POST with the form data, and create the new 'fact' resource. This seems like an even worse approach.
Don't send the form over the wire, but include it as part of the API. This seems RESTful since a REST API should describe the media types, and a form can be made from a description of the 'fact' type. This is weird to implement. Maybe the REST service is separate from the regular web site, so that the actual HTML form request is at some URI apart from the REST API.
Include the HTML form as part of the 'facts' URI response.
To clarify, I'm trying to follow true REST architecture as specified by Roy Fielding, not half-baked RPC posing as REST.
edit: I'm starting to think #3 is on to something.
edit2: I think a solution is to have regular non-REST HTML navigation in a CRUD manner, and then the frontend makes AJAX REST calls as appropriate (or the backend makes internal calls to its REST API).
The reason I need to do the REST part of this service correctly is that I want to allow other non-HTML clients to interact with it later on.
In my mind, the only cleanly RESTful answers are 1 and 3.
As I see it, the description of the resource is a resource of its own. The question is whether you want to make this resource accessible through your application's API or if you want to make it part of the API itself.
For 1, it seems RESTful make the URIs something like this:
GET /facts -> all facts
GET /facts/1 -> returns fact 1 (obviously the id might be a word or something else)
GET /facts/create -> returns a form appropriate for creating a fact
POST /facts -> adds a fact
I think you're overcomplicating things a bit. A web browser is just not a perfect REST client, so you can't have a perfectly RESTful solution. In a perfect world, you would not need a form at all, because the web browser would know your media types and build the form itself.
Meanwhile, I suggest you just use what most REST frameworks would call an additional "view" on the resource to return a form:
E.g. /your/collectionresource?view=form, or /your/collectionresource;form