3

I am using a REST API that is being developed at my workplace. The documentation clearly states the HTTP request type (POST), the URL endpoint, and the "payload" in curly brackets, i.e., various parameters and expected values. At the bottom of each endpoint section, it details response possibilities as response codes - 200 for success, 400 for an error, and so on. It doesn't say anything about what the API call will return if successful, i.e., a nested list of different data attributes and so on, so you can know what to expect and how to swiftly extract the data you are seeking; and these methods must certainly return data, by their nature.

Is it common to leave out the structure of the response data in a REST API documentation or is this poor practice?

10
  • 2
    It definitely helps to have it but my experience with building APIs is that a lot of the time, the client developers don't look at it and just assume what comes back is representative of what they will always see. You might want to ask about what tooling they are using to generate this. They may not be taking full advantage of it.
    – JimmyJames
    Commented Oct 12, 2021 at 15:04
  • surely REST requires no documentation
    – Ewan
    Commented Oct 12, 2021 at 18:00
  • 1
    I'm wondering whether @Ewan's comment and the answer by Robert Bräutigam below are somehow sarcastic and I'm just not getting the joke, or meant seriously.
    – Hans-Martin Mosner
    Commented Oct 13, 2021 at 5:25
  • slightly sarcastic. by the book REST needs no documentation, its kind of the point. No-one does REST by the book, but everyone says REST is amazing and everything should be RESTful.
    – Ewan
    Commented Oct 13, 2021 at 9:06
  • 1
    @Ewan Are you not aware of JSON Schema, or are you just saying it isn't "nice"?
    – IMSoP
    Commented Oct 13, 2021 at 17:01

4 Answers 4

Reset to default
3

It is probably both common and poor practice :-) (I don't have enough experience with what others do to leave out the "probably")

Have a look at OpenAPI (https://www.openapis.org/) and Swagger (https://swagger.io/). They have a rich model for expressing API specs and documentation, and there exists tooling for many languages. Since the format is well-documented, it is possible to create well-readable documents from OpenAPI JSON. The spec places emphasis on providing data structure documentation as well as API endpoint docs.

OpenAPI does not enforce that the API implementation actually conforms to the specification, but in cases where API provider and consumer disagree, it is a good reference for deciding which one should adapt.

1
  • 1
    Based on the description in the question, it sounds like they are using something like swagger or redoc but are not generating/documenting the response schema. When I first started using FastAPI, for example, I wasn't specifying the pydantic models that it uses to generate those schemas so I would get something like what is described in the question.
    – JimmyJames
    Commented Oct 12, 2021 at 16:59
0

Actually, no it should not. What resource / page a server returns to you after processing your request is up to the server and may change without notice depending on some state, context, parameters or software updates, etc.

As long as the server can send media types that the client understands, the client does not need to know the type / structure of resource that will be returned in advance.

It is also completely unnecessary to document return codes (those are part of the HTTP specification and their meaning is known already) or URIs / parameters / methods (hypermedia will specify those).

If you use none of that and hardcode everything into the client, then sure, document the return structure.

27
  • The question was about an API, not a web server where you'd expect a human to decipher the response as rendered by their browser. The interpretation of API responses is typically hardcoded into the client.
    – Hans-Martin Mosner
    Commented Oct 13, 2021 at 5:16
  • @Hans-MartinMosner The question was specifically about REST APIs, which were originally designed to work just like websites. I know, it is not used that way today, you're right. I sometimes feel though the decision to ignore what its original purpose was is not made deliberately, so it has some value to mention how it supposed to work.
    – Robert Bräutigam
    Commented Oct 13, 2021 at 6:22
  • 1
    @RobertBräutigam Frankly, I don't think this answer is helpful to the OP. It's impractical to think that people are going to register new MIME types or whatever for each new document they need to return or that the client developers are going build code to discover the API every single time they call it. I think it's time to accept that the term REST API has gotten away from Fielding. Yes, this is not what he meant but it's what most people mean when they talk about REST. I feel bad that his term got hijacked but it's over. He doesn't even blog about it anymore, to my knowledge.
    – JimmyJames
    Commented Oct 13, 2021 at 16:19
  • 1
    @JimmyJames You're right I think and I sort-of (?) accept that REST means almost the opposite of what it was supposed to mean. I still think the original way (or a much more closer interpretation) is much more practical and maintainable though (having designed such APIs myself). It just seems impractical because nobody seems to have a good example and most do not even know there are other ways to do it. I understand everyone in this thread, I just would like to leave the "other" (original?) way here for reference and hope that it provides value for people looking for that explicitly.
    – Robert Bräutigam
    Commented Oct 13, 2021 at 17:17
  • 1
    @JimmyJames I've used the vendor and unregistered trees for company / internal stuff. (en.wikipedia.org/wiki/Media_type#Vendor_tree) Don't need to register everything. The beauty of Mime-types is that you concentrate on what it means, not technical details, therefore simple text is sufficient. As to dealing with changes, discovery and content-negotiation. It is not that difficult once you commit. Here is my small experimental library for how it could be done: github.com/vanillasource/gerec/wiki/Navigation
    – Robert Bräutigam
    Commented Oct 13, 2021 at 19:56
0

There are two, somewhat orthogonal questions, here:

  1. Should an API provide documentation on its outputs as well its inputs?
  2. How should that documentation be provided in the context of a RESTful design?

The answer to question 1 is a resounding "yes": any client needs to have knowledge somewhere of what information it can retrieve from an API, or the API has no practical use. If I want to display some products results from your API, I absolutely need to know whether they have a description, an image URL, etc, and how to extract those from a particular representation.

The answer to question 2 is much more subtle. In a true REST design, there are no defined URLs, and so there can be no defined responses from sending requests to those URLs. Instead, there are defined content types, and defined relationship types.

Content types are fairly straight-forward to think about: think about XML or JSON schemas for entities like "Product" or "SearchResultList", but then add the semantics (meaning) as well as the syntax (structure and format). All the requests and responses used by the API should use documented content types.

Relationship types are less easily understood, and the part that few "RESTish" APIs actually implement. I will also probably explain it really badly, so take everything in this paragraph with a grain of salt, and read up on "HATEOAS" if you're interested. The idea is that as part of a content type like "SearchResultList" would be elements which are simply links to other API end-points, each labelled with an identifier. Those identifiers would then be documented separately from that particular type, e.g. "wherever you see a 'product-item' link, the URL is somewhere you can fetch a 'Product' entity".

So in a true RESTful API, there should never be a document saying "URL /products/42 will return JSON in this format", because there should be no document specifying the URL /products/42 at all. But you definitely need to document your data representations somewhere.

-1

If I were tasked with writing code which intended to use the API, then yes I would need a definitive description of what exactly to expect. Don't leave me guessing. Don't waste my time.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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