Skip to main content
Software Engineering

You are not logged in. Your edit will be placed in a queue until it is peer reviewed.

We welcome edits that make the post easier to understand and more valuable for readers. Because community members review edits, please try to make the post substantially better than how you found it, for example, by fixing grammar or adding additional resources and hyperlinks.

Required fields*

15
  • 1
    Excellent. This is what I was trying to explain in my comments but had trouble articulating. Commented May 1, 2019 at 18:26
  • Thanks for this thorough answer! To answer your first paragraph, no I don't allow POST requests on /documents/{schema}/, only on /revisions/{schema}/{document}/{role}/ (see my answer). In my suggested URI structures, the representations of collection resources (such as /documents/{schema}/) consist only of links to child resources (such as /documents/{schema}/{document}), they have no own data. If you want to access or modify a schema you use this URI: /schemas/{schema}. Commented May 1, 2019 at 18:39
  • 1
    @Maggyero So to fully request an entire list of documents, you have to make 1 request to get the links, and then N requests to fetch the data for each document in the list for a total of N+1 requests? One problem people seem to always have when designing APIs is they attempt too much to predict how a client will use them. A client will use it as it is required to, and requirements change over time. Your API should be flexible enough to not require a ton of changes every time a requirement gets added to the client. Commented May 1, 2019 at 18:43
  • Yes, but it is the same with your URI structure: GET /documents/ return the links, as I understand it. Commented May 1, 2019 at 18:47
  • @Maggyero Sorry, that's not how I had understood it. I would suggest returning the actual collection of data and not just links to the data for that very reason. If the data set is potentially large, you can paginate the results on the server using either page-based or cursor-based pagination. Commented May 1, 2019 at 18:48