CODEWITHSUNDEEP
apiswaggerapi-design
doub1ejack
doub1ejack

Reputation: 11181

API design pattern for specifying different response models

I'm trying to rough out an api for returning article content. It seems valuable to be able to specify whether we want the entire article, a summary, or possibly some other variation on that content.

My instinct is to add a query parameter to a GET request like dataModel (feel free to suggest better names). For instance, the default may be the entire article, but summary may just be id, title, & description, and list might return id, title, author, & lastModifiedDate.

However we are using Swagger for documentation and Swagger doesn't appear to support returning different objects based on query parameters (see this). So I'm wondering if there are other established patterns that would be equally acceptable?

Upvotes: 0

Views: 492

Answers (2)

fehguy
fehguy

Reputation: 6824

The right solution with Swagger is to create a return type that contains common properties across all the data models. Then you can model a discriminator and use the allOf constructs for creating the proper response type.

If you take a look at the sample definition here:

https://swaggerhub.com/api/swagger-tutorials/modeling-samples/1.0.0

You'll see how it can be done with an Animal return type, and Cat and Dog concrete types.

Upvotes: 3

William Cheng
William Cheng

Reputation: 10817

One workaround is to use path variables instead of URL query string for dataModel and use the following route instead

  • /v0/articles/{id}
  • /v0/articles/{id}/summary (returns a model with id, title & description)
  • /v0/articles/{id}/list (returns a model with id, title, author, & lastModifiedDate)

Upvotes: 0

Related Questions