Open zeluspudding opened 5 years ago
I've updated my question with better examples.
The reason they are strings and not numbers is because the default type is string and the value isn't set as a number type. If you change the following they will become numbers:
+ `years_of_operation`: 23 (number)
+ `years_of_operation`: 16 (number)
Right - that's what I thought MSON would handle (since years_of_operation
was already defined as a number
in the data structure Restaurant
. So then MSON doesn't help eliminate the need to explicitly restate data structure definitions in this case?
... So the benefit of using a data structure in this case is nill? I hope I'm not coming across as sour on this. I'm just genuinely trying to understand if there is a benefit to using a data structure in this case. API Blueprint is pretty awesome!
In a larger API, MSON gives you a way to reuse a data structure. Given perhaps a CRUD version of a restaurant API you could do something like the following:
# Restaurant API
## Restaurants Collection [/restaurants]
### List all restaurants [GET]
+ Response 200 (application/json)
+ Attributes (array[Restaurant], fixed-type)
### Create a Restaurant [POST]
+ Request (application/json)
+ Attributes (Restaurant)
+ Response 200 (application/json)
+ Attributes (Restaurant)
## Restaurant [/restaurants/{id}]
+ Parameters
+ id: 1 (number)
### View [GET]
+ Response 200 (application/json)
+ Attributes (Restaurant)
### Update [PATCH]
+ Request (application/json)
+ Attributes (Restaurant)
+ Response 200 (application/json)
+ Attributes (Restaurant)
### Delete [DELETE]
+ Response 204
# Data Structures
## Restaurant
+ `restaurant_name`: McDonald's (string, required) - The name of this restaurant
+ `years_of_operation`: 54 (number, required) - The number of years since established
In your particular use-case I agree with you that how MSON works doesn't quite work well for that particular case.
If you wanted to perhaps copy a real world response for an example over you could also do something like the following where I've included an actual JSON body alongside the attributes. As another option.
### List all restaurants [GET]
+ Response 200 (application/json)
+ Attributes (array[Restaurant], fixed-type)
+ Body
[
{ "restaurant_name": "x", "years_of_operation": 5 },
{ "restaurant_name": "y", "years_of_operation": 6 },
{ "restaurant_name": "z", "years_of_operation": 5 }
]
In terms of rendering in Apiary documentation, it will then only keep 1 example which may be desired to keep the attributes section small and compact and just including the base structures (and not any larger examples):
While the JSON example, and the mock server would show the included example:
Hmmm, that last half is helpful. Thank you so much Kyle!
Looks like you have to declare the sample data for each member of the array; it doesn't give defaults:
### List all restaurants [GET /restaurants]
+ Response 200 (application/json)
+ Attributes
+ data (array)
+ (Restaurant)
+ restaurant_name: McDonald's
+ years_of_operation: 54
+ (Restaurant)
+ restaurant_name: Bob Evans
+ years_of_operation: 23
+ (Restaurant)
+ restaurant_name: Eataly
+ years_of_operation: 16
I have many places in my API where I will need to describe a list of objects. Each object has the same keys / structure but different values. How can I tweak the values of each instance of some data structure while retaining all the original type, description, etc of the original structure?
for example if I had the following data structure
Restaurant
Then, let's say I want to instantiate several
Restaurants
in a GET response like so:the JSON body would look like this (note how
years_of_operation
for Bob Evans and Eatly are now numbers)and the rendered documentation will only show this (the descriptions for
restaurant_name
andyears_of_operation
for Bob Evans and Eatly are now missing)I thought that MSON would carry over those descriptions and type definitions. Otherwise, I have to update a description (or type, requirement, etc) everywhere that data structure is used... but I was under the impression this is a sort of problem MSON is supposed to solve? Am I doing something silly?