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
# Data Structures
## Restaurant (object)
+ restaurant_name: McDonald's (string, required) - The name of this restaurant
+ years_of_operation: 54 (number, required) - The number of years since established
Then, let's say I want to instantiate several Restaurants in a GET response like so:
### List all restaurants [GET /restaurants]
+ Response 200 (application/json)
+ Attributes
+ data (array)
+ (Restaurant)
+ (Restaurant)
+ restaurant_name: Bob Evans
+ years_of_operation: 23
+ (Restaurant)
+ restaurant_name: Eataly
+ years_of_operation: 16
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 and years_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?
I'm posting here in addition to my github issue since it's been a long time since that repo has had contribution
Related
I am working on a search filter atm where people can specify things like (example) size, color, fabric and so on.
Obviously I have models for each i.e. size, color and fabric. But since this "search" should return every result i.e. size + color + fabric and not just one of the three I would need to make a new struct which contains all the (size, color and fabric) to be able to consume the result that Gorm would return.
Since we have a LOT of filters, this could get very messy. Does anyone know if there is a better way to do it? or what would be a best practice to do this?
type Result struct {
ID int
Name string
Age int
}
var result Result
db.Raw("SELECT id, name, age FROM users WHERE name = ?", 3).Scan(&result)
The above example illustrates how I think it should be done, but as you can expect with the amount of data I need to return this struct would become huge.
The results are quite large in terms of data. I mean what I would want in return in the final version for example (this is about sales):
What products were bought, the amount, color and size. Payment data i.e. price, tax, payment method. Customer information, et cetera.
So in total there is a lot of information to store.
All this information should be returned as a JSON format so we can call it through an API call.
Each call should give back 100 up to 15.000 results, to give you an idea of the side of the data.
Hope someone can explain a bit about a best practice method and -or how I should solve this problem as I am unsure on how to code this effectively.
We have a querystring parameter called imageDimensions, which specifies the desired dimensions for images of different types.
e.g. ?imageDimensions=poster:600x800,badge:100x100
Is there a way in API Blueprint to specify that imageDimensions should be a comma-separated list of image dimension specs, each of form "(image type):(width)x(height)"?
There is no good dedicated syntax for it at the moment. I would probably go with something like:
## GET /resource{?imageDimensions}
+ Parameters
+ imageDimensions (string, optional) - Comma-separated list of image dimension specs, each of form `(image type):(width)x(height)`
Where the `(image type)` is one of the following:
- badge
- poster
- icon
+ Sample: `badge:100x100`
+ Sample: `poster:600x800`
+ Sample: `poster:600x800,badge:100x100`
+ Response 200
Note, it is planned to move the parameters syntax to full MSON syntax in the near future. See the API Blueprint roadmap.
With it, it should be possible to define types for images as an enum and then reference it in the blueprint.
I'm maintaining a small program that goes through documents in a Neo4j database and dumps a JSON-encoded object to a document database. In Neo4j—for performance reasons, I imagine—there's no real data, just ID's.
Imagine something like this:
posts:
post:
id: 1
tags: 1, 2
author: 2
similar: 1, 2, 3
I have no idea why it was done like this, but this is what I have to deal with. The program then uses the ID's to fetch information for each data structure, resulting in a proper structure. Instead of author being just an int, it's an Author object, with name, email, and so on.
This worked well until the similar feature was added. Similar consists of ID's referencing other posts. Since in my loop I'm building the actual post objects, how can I reference them in an efficient manner? The only thing I could imagine was creating a cache with the posts I already "converted" and, if the referenced ID is not in the cache, put the current post on the bottom of the list. Eventually, they will all be processed.
The approach you're proposing won't work if there are cycles of similar relationships, which there probably are.
For example, you've shown a post 1 that is similar to a post 2. Let's say you come across post 1 first. It refers to post 2, which isn't in the cache yet, so you push post 1 back onto the end of the queue. Now you get to post 2. It refers to post 1, which isn't in the cache yet, so you push post 2 back onto the end of the queue. This goes on forever.
You can solve this problem by building the post objects in two passes. During the first pass, you make Post objects and fill them with all the information except for the similar references, and you build up a map[int]*Post that maps ID numbers to posts. On the second pass, for each post, you iterate over the similar ID numbers, look up each one in the map, and use the resulting *Post values to fill a []*Post slice of similar posts.
I have a data structure defined as follows:
# Data Structures
## PlayerRank (object)
Represents the minimum amount of data the the client needs to send to give rank information about a particular Player in a particular Played Game.
+ playerId (number, required) - NemeStats unique identifier for the Player.
+ gameRank (number, required) - The corresponding rank of the Player in this Played Game. A rank of 1 means the Player got first place, 2 means second place, and so on.
+ pointsScored (number, optional) - Integer number of points the Player scored in the Played Game.
I'm attempting to use this data structure in another action definition as follows:
## Create a new Played Game [POST]
This service will record a new Played Game.
+ Attributes
+ gameDefinitionId (number, required) - NemeStats unique identifier for the Game Definition (e.g. Race For the Galaxy's unique Id) of the Played Game.
+ datePlayed (string, optional) - The date the game was played in yyyy-MM-dd format (e.g. 2015-04-29).
+ notes (string, optional) - Any notes or comments that the User wants to record about the game for future reference.
+ playerRanks (array[PlayerRank], required) - A collection of PlayerRank objects specifying the game rank and points scored for each Player. See below table for details.
What I want to happen is for the Apiary.io Documentation to show the definition of not only the top level attributes but also those of the PlayerRank object. As a developer trying to understand the UI, I want to see the definition of each object and field so I know how to properly form a request. Right now it only gives the description for the playerRanks object which is : "A collection of PlayerRank objects specifying the game rank and points scored for each Player." but it doesn't expand the definition to show all of the properties of a PlayerRank data structure.
Any idea if the Apiary.io documentation can facilitate this?
now Apiary, API Blueprint supports nested objects which you can define as below for example
+ Attributes (object)
+ name: iPhone 6 / 6s (string, required) - Offer Name
+ price: 10.4 (number) - Offer price
can be a number with 2 decimal places, this is the sale price
+ offer_options (object)
+ option_name: black (string, required) - offer option name
+ max_qty: 0 (number) - Purchase limit to this quantity
AFAIK it's a beta feature and the UI is not finished yet, see this github issue for more information and sneak preview of the birght future.
Reading the API Blueprint specification, it seems set up to allow one to specify 'Data Structures' like:
Address
street: 100 Main Str. (string) - street address
zip: 77777-7777 (string) - zip / postal code
...
Customer:
handle: mrchirpy (string)
address: (address)
And then in the model, make a reference to the data structure:
Model
[Customer][]
It seems all set up that by referencing the data structure it should generate documentation and examples in-line with the end points.
However, I can't seem to get it to work, nor can I find examples using "fully normalized data abstraction". I want to define my data structures once, and then reference everywhere. It seems like it might be a problem with the tooling, specifically I'm using aglio as the rendering agent.
It seems like all this would be top of the fold type stuff so I'm confused and wondering if I'm missing something or making the wrong assumptions about what's possible here.
#zanerock, I'm the author of Aglio. The data structure support that you mention is a part of MSON, which was recently added as a feature to API Blueprint to describe data structures / schemas. Aglio has not yet been updated to support this, but I do plan on adding the feature.