How to GET and provide arguments?


#1

I need to make a GET request for a PDF that requires the user’s timezone offset. The reason being, the service needs to return a generated PDF with the GMT timestamp formatted to the user’s local time.

The Java engineer proposed this:

/pdfs/{id}?timezone_offset=-7

However, if I’m to stick with the standard usage of keywords in the query string (i.e. filter, sort, etc.), I would expect timezone_offset to be a parameter that follows a particular keyword. Does one exist?

I’m considering using meta.

/pdfs/{id}?meta[timezone_offset]=-7

Any suggestions would be appreciated.


#2

we have the same need (providing query parameters which are not filters) and we got to the same solution (but we are using “criteria” as keyword).


#3

Hello,
Maybe I’m wrong but It seems to me that “meta[timezone_offset]” doesn’t fit with the specifications.

Implementation specific query parameters […] MUST contain at least one non a-z character

So I think “meta” is not a valid candidate but it should not be too complex to find a naming with a capital letter or ‘_’.

And I have a question : As the PDF is generated, a POST would not be more accurate than a GET ?


#4

I think POST is a perhaps the better choice. If using GET, criteria isn’t a bad choice as @malras suggested.


#5

This is a case where i think this spec falls down some. There are all these REST frameworks that do the heavy lifting of binding normal HTTP parameters to variables, validating, sanitizing, and providing to the application layer. And this criteria thing breaks all of them.

If we switched to criteria[ … ] the application back-end has to parse that list, validate it, make sure it is a sane request, and then go find the right block of business logic. Whereas with a normal http parameter all of that is done for us and it is something that everybody with a little web experience can recognize.

In this case I also think a POST is a little odd. I see that a POST might fit the json-api spec but it sort of ruins HTTP in general I think. You issue a post and in the response you get a multipart message that represents a PDF? Seems like a GET to me. Additionally the body of the POST is a single piece of meta-data? Doesn’t seem right or natural to me.

I could easily be missing something about the spec but I would be curious to hear thoughts on this.

[Full disclosure: I work with Andrew on our implementation using the spec which includes some special challenges including the need to run on java 6 in the back end for the time being.]


#6

Does the generated PDF get stored on the back-end, or is it just returned to the client? If it is stored then a POST seems appropriate, otherwise GET would seem to be a better fit.

A way round this might be to break this into two stages:

  1. a POST to create a “PublishedPDF” resource that includes a Relationship (this request would contain the timezone offset and the PDF ID)
  2. a GET to the related link of the relationship to obtain the generated PDF

#7

@jlangley My understanding is that the PDF is generated upon request. I don’t believe the document is then stored on the server for future reference. Perhaps @joe_white101 can inform on that.

I’m not in favor of breaking using two requests. For me, JSON API’s value is in the ability to format bulk updates within a single request.


#8

As it stands now, based on @joe_white101’s comment: How to GET and provide arguments?, we’ve decided to go with:

?timezone_offset=-7


#9

@andrewhenderson is correct. We regenerate the PDF on every request. The data behind the PDF is subject to constant change and the generation is handled transactionally in a dedicated microservice so the performance is reasonable.


#10

Actually the spec might be irrelevant here - I don’t think you can return a PDF from a JSON API endpoint. I think you have to expose the URL for the PDF as an attribute, then interact with that. But that endpoint is not governed by JSON API, so you can do whatever you like there. You might be interested in this discussion