2

For example, I create an API endpoint that provides the next available label for creating some items, so I call it like this:

GET /api/v1/get-next-label/

Is it ok to return just:

LBL-000001

Or is it better practice / or there is an argument to return something like:

{
    "label": "LBL-00001"
}
4
  • 2
    It is OK to return just the value. – JacquesB May 17 at 21:10
  • Might not apply here, but what if there is no next value? Due to an error, improper authorization, or whatever. JSON supports that more cleanly. – user949300 May 18 at 6:04
  • 1
    If there is no next label you should return a HTTP status code for why it can't be accessed (a 4xx error or 5xx error). Whether the body of that response is txt or json is really here nor there, the client should know something has failed due to the HTTP response. Also the body of the resource and the body of a 4xx/5xx error can be in different formats, just because you use JSON in a successful Get doesn't mean you have to use JSON in your error response, and vice versa – Cormac Mulhall May 18 at 13:45
  • 4
    FWIW, some calls returning JSON and others returning other things makes life more complicated for anyone connecting to your API. If instead, every call returns a JSON payload, that is one less possible point of pain, one less place of "whoops" and spending a bunch of time figuring out why something is wrong. I've connected to APIs that sometimes pass arguments in query params, sometimes in POST bodies, returns in JSON or just the values, and it is super obnoxious to spend a bunch of time debugging something because you've mixed up which uses which. – whatsisname May 18 at 18:53
2

Its your API.

Just be consistent, and document it.

The only times you don't get to choose is when you are implementing someone elses standard. Be that you are duplicating some other api, or that you are taking a specific communication standard and deriving your own variant implementation.

eg:

  • Implementing you own POP email Server
    • Someone elses API, endpoints, headers, and responses: which you must match
  • Implementing your own Web API
    • Http prescribes how and what endpoints, headers, and content can be used. But within that you are free to choose whatever you want.
2

If you have an approach that fits your needs better, I would not hesitate to drop JSON. However, there are a few things to consider:

  • JSON is kind of standard. You clients will most likely have a way to decode it anyways. This is not necessarily true of other (especially custom) encodings.

    Of course, if your responses consist only of primitives, such as integers, floats, and strings, this is not a big issue.

  • Make sure you can represent every state appropriately. Can you distinguish between an empty string/list/etc. and a missing one?

  • Your API should be consistent. Don't use JSON in some cases, but something else in others. Both the server and the client must have a way to work with JSON in this case, and using that ability only sometimes does not gain you much, but makes the API much harder to use.

  • Consider that APIs tend to evolve over time. You might only need one value today, but what about tomorrow? JSON fields can be added in a backwards-compatible manner. What do you do when you have plain-text data?

1
  • APIs tend to evolve over time you release version 2 of your API, or add another end-point. Unless you have complete control over the clients of the API (eg internal business only) then never ever change the API behaviour once its formally published. – Kain0_0 May 18 at 23:00

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.