2

I am following swagger-driven api development. While skimming codebases, i observe that services return a parent object whenever there is an expectation to return a list of objects.

The reason being given is 'it is bad practice to return list of objects in api'. Most likely this popular tutorial is the source of inspiration :- https://www.youtube.com/watch?v=Dmvhe2cw-_k It says 'the api could break if the service returns an object instead of a list'

However, i am not convinced with this one-size-fits-all dictum, since every api contract is documented in swagger and all developers have to strictly follow the document to develop their services and service calls.

I still prefer returning a list of objects over returning a wrapper object. What do the experts suggest ?

Links to any documentation, developer guides for best practices are most appreciated.

user1354825
  • 1,108
  • 4
  • 21
  • 54
  • 1
    It's perfectly fine to return a list. In the Video returning an object is only suitable if you need to return data on toplevel beside the list. – Simon Martinelli Jul 30 '20 at 12:31
  • APIs adhering to a Swagger/OpenAPI/... documentation [have hardly anything to do with REST](https://stackoverflow.com/questions/54839672/difference-between-swagger-hateoas/54841309#54841309) – Roman Vottner Jul 30 '20 at 12:39
  • There are (really) [No Best Practices](https://www.satisfice.com/blog/archives/5164) ... so asking for a link to a list of them here is doubly wrong. (It is also off-topic.) – Stephen C Aug 19 '20 at 01:03

1 Answers1

2

If it is a 'collection' resource such as:

/employees

Then as a consumer, I would expect a list of items + any pagination details (It would also be really helpful to receive some aggregate information on the total number of employees matching the criteria (if you provide some query params) etc)

This guide should help you understand more about the different types of resources https://restfulapi.net/resource-naming/

API Alex
  • 106
  • 1
  • 1
  • 6