0

I'm building a simple app that is a client web application and an API behind it. I'm combining two third-party APIs, one needs to be called from my client application (for ease of authentication) and one needs to be called by the server.

The data I receive from my first API is a list of strings - it will be between 0 and 150 items long, each string is an unknown length. Each one of these items needs to be passed to my server - either as individual elements (preferred) or as a serialised string. My endpoint will always return a single object, regardless of how many items are passed to it.

What is the most semantic way of passing this data to my API?

It's not really a GET request as the returned object is dynamic, and I'm concerned about the URL length limits (discussed here) given that I don't know what these strings will look like.

POST also feels incorrect as I'm not going to storing what is sent to me, though this would allow me to send the data in the body of the request and not worry about the size.

Perhaps I shouldn't worry so much about semantics and just do what works, but I'm interested in opinions on the best, or 'proper', way to design my API here.

  • 3
    What do you mean by "most semantic?" Semantics are not good or bad; they just are. The semantics you choose to use will depend largely on your specific requirements. – Robert Harvey Apr 19 at 20:14
  • 3
    Don't say "best practice." That's just saying the same thing. – Robert Harvey Apr 19 at 20:17
  • 2
  • 2
    Instead of using words like "proper" (which is what you do when you wear a suit to dinner and make sure your salad fork is in the right place on the table) and "best practices" (we don't know what "best" means to you), think about your requirements and ask yourself "which approach is most optimal for my specific requirements? – Robert Harvey Apr 19 at 20:20
  • 1
    Seems as if the post @JonRaynor linked constrains you to using POST. – Robert Harvey Apr 19 at 20:28
2

It's not really a GET request as the returned object is dynamic

Not really relevant. "Resources", the things identified by uniform resource identifiers, are not fixed in time

Some resources are static in the sense that, when examined at any time after their creation, they always correspond to the same value set. Others have a high degree of variance in their value over time. The only thing that is required to be static for a resource is the semantics of the mapping, since the semantics is what distinguishes one resource from another -- Fielding, 2000.

You wrote:

I'm concerned about the URL length limits

That's a legitimate problem.

Fundamentally, HTTP really didn't evolve with the use case "safe operation that takes a query document as an argument" as part of its primary supported set.

The closest you can get to "answer a question about my document" is probably "copy my document; answer a question about your copy of my document". While you can compress away the second part of that by inlining it into your response, the first part of the request is inherently unsafe, so you need to be looking at POST/PUT/PATCH.

In some cases, you can find that a method has been registered that fits your use case, and then you are good to go. And of course defining your own method is always an option.

I shouldn't worry so much about semantics and just do what works

The good news is that POST "just works" and has very flexible and forgiving semantics.

  • In some cases, you can find that a method has been registered that fits your use case Inventing a method is not the problem. The problem is whether your libs (HTTP clients) support them and, if not, if you can expand the libs. On both sides, server and client. – Laiv Apr 23 at 13:10

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.