I have an API contract defined in Apiary and I'm using the Resource model syntax to enable reuse of payloads.
The documentation rendered by Apiary only shows the model name though (eg Response 200 returns a [Foo][]) - without any further details on what Foo is, or any link to view the attributes in the Foo model.
Given a model, how do I see what its attributes are in the rendered documentation?
update
The relevant part of the contract is below:
### Manipulating a specific Organisation [/organisations/{id}]
Operations to retrieve and update a specific Organisation.
+ Parameters
+ id (required, guid, `F339ADA5-E836-40FE-8E90-BEF06892762E`) ... The guid Organisation `id`.
+ Model (application/json)
+ Headers
Link : <http://foobar.com/organisations/F339ADA5-E836-40FE-8E90-BEF06892762E>;rel="self"
+ Body
{
"id" : "F339ADA5-E836-40FE-8E90-BEF06892762E",
"name" : "joe's gardening supplies"
}
### Retrieve an Organisation [GET]
+ Response 200
[Organisation][]
### Update an Organisation [PATCH]
+ Request
[Organisation][]
+ Response 204
Unless you provide an example, it's just guessing, but my first guess would be wrong level of indentation. How example blueprint could look like:
FORMAT: 1A
HOST: http://www.google.com
# Model Example
Notes API is a *short texts saving* service similar to its physical paper presence on your table.
# Group Notes
Notes related resources of the **Notes API**
## Note [/notes/{id}]
A single Note object with all its details
+ Parameters
+ id (required, number, `1`) ... Numeric `id` of the Note to perform action with. Has example value.
+ Model
+ Header
X-My-Header: The Value
+ Body
{ "id": 2, "title": "Pick-up posters from post-office" }
### Retrieve a Note [GET]
+ Response 200 (application/json)
[Note][]
### Remove a Note [DELETE]
+ Response 204
Code above results in this documentation, where model is correctly incorporated on places where it's referenced (and where such reference is supported - i.e. definition of payload).
Sometimes it's helpful to read the raw version of Apiary's docs on GitHub, because it's easier to spot the right, exact format that way.
ok, from comparing the two examples I've worked it out.
in my contract the model reference
[Organisation][]
was indented two tabs instead of one. :S
that's a really easy mistake to make - would be helpful if Apiary flagged the incorrect indentation level for a model reference.
Related
I am using django rest framework documentation module to document my API.
I am facing a problem in the sense that nested serializers do not appear in my documentation, but only the outermost does.
As an example I have the following code:
class MyFirstSerializer(serializers.Serializer):
some_data = serializers.CharField(help_text="a number")
more_data = serializers.CharField(help_text="a letter")
class MySecondSerializer(serializers.Serializer):
email = serializers.EmailField(help_text="the email address")
number = serializers.CharField(help_text="a number")
another_serializer = MyFirstSerializer(help_text='a JSON structure')
The way the program works, is by having a nested JSON structure. However the documentation modules on mentions the fact that another_serializer is a field, and does not show what kind of data is supposed to be passed, somethinng like:
POST your/endpoint/
Parameter Description
email the email address
number a number
another_serializer a JSON structure
I would like a way for the documentation to be done recursively on all my field, in order to have a complete description of my endpoints, something like:
POST your/endpoint/
Parameter Description
email the email address
number a number
another_serializer
some_data a number
more_data a letter
How can I ommit property from defined MSON? I have defined one simple entity (object) using MSON:
# Data Structures
## Article (object)
Represents an article
## Properties
+ id: 1 (number, optional)
+ name: My first article (string)
## Articles [/articles]
### Get all articles [GET]
Get all articles available on this website.
+ Response 200 (application/json)
+ Attributes (array[Article])
### Create an article [POST]
Create new article.
+ Request (application/json)
+ Attributes (Article)
I'm using Article object in several api endpoints. The problem is that I don't want id to be specified when posting new article so I want to omit it in the documentation for POST method. Is it possible to include Article entity in all endpoints and say what fields I want to omit?
There is no actually way how to do it.
You have two options:
declare id with attribute nullable
Declare Article without id and later inherit from Article and attach id.
# Data Structures
## Article (object)
+ name: My first article (string)
## ArticleInstance (Article)
+ id (number)
## Articles [/articles]
### Get all articles [GET]
Get all articles available on this website.
+ Response 200 (application/json)
+ Attributes (array[Article])
### Create an article [POST]
Create new article.
+ Request (application/json)
+ Attributes (Article)
Resources usually have multiple get methods. Get a singular or get many by query params. How is this represented in blueprint? I can do it using two resources, but that in my opinion is not correct as its the same resource.
Related to this question How does one add PUT to the resource given the uri is defined at the resource level.
Ideally this is how i think things should be written but the editor doesn't like it. I have found in docs where the HTTP_ACTION and URI can be put together, but the editor seems to want the URI at the resource level.
# Storefronts
## Read [GET /v1/storefronts{?query_params...}]
+ Parameter
query_params ...
+ Request Matching Storefronts (application/json)
+ Response 200 (application/json)
## Read [GET /v1/storefronts/{id}]
+ Parameter
+ id (string) ... id for record to return
+ Request (application/json)
+ Response 200 (application/json)
## UPDATE [PUT /v1/storefronts/{id}]
+ Parameter
+ id (string) ... id for record to update
+ Request (application/json)
+ Response 200 (application/json)
Technically you have 2 resources: one representing a single Storefront with an identity (typically supporting GET, PUT, DELETE, PATCH) and one representing a collection of Storefronts (typically supporting GET, POST). Here's how you would represent this in API Blueprint:
# Storefront [/v1/storefronts/{id}]
## Retreive a Single Storefront [GET]
## Update a Storefront [PUT]
## Delete a Storefront [DELETE]
# Storefronts Collection [/v1/storefronts]
## List Storefronts [GET]
## Create a New Storefront [POST]
I have a set of legacy database tables that i cannot normalize out to what should have been done in the first place. e.g one big table with 200 columns.
I'm building an API and would like to represent this data to the consumer in a better state, and perhaps address the database issues at a later stage, there are many backend systems that reply on the data and changes are not easy.
I wanted to represent the current database schema using Active Record, however perform a model transformation into a new model that will be used for presentation only to an API consumer as json data.
current database schema:
Products table (200 columns)
New Model:
Product
+ Pricing
+ Assets
+ Locations
+ Supplier
I could hard-code a json string in a template, but feel that would not be a very poor approach.
What approach or gem would you recommend to tackle this best?
I have looked at :
RABL
ActiveModel::Serializers
If you define an as_json method that returns a hash, ActiveRecord will take care of the serialization for you. E.g.
class Product < ActiveRecord::Base
def as_json options = {}
{
product: <product value>,
pricing: <pricing value>,
# ... etc.
}
end
end
Now you can do:
> Product.first.to_json
=> "{\"product\":<product_value> ... }"
You can even render these as json from the controllers via:
render json: #model
I'm trying to implement chained drop down boxes using the tutorial here. My classes are not as straight forward as the ones in the tutorial though.
I want to chain the drop down boxes for the create.gsp view in the Load class. Each load belongs to an account from the Account class, and each account belongs to a user from the User class, and each user has several cargo destinations from the Address class.
My goal is to have the cargo destination field up date based on which account is selected.
I am having trouble understanding the AJAX function in the tutorial (step 3), and how it relates to the Grails function (step 4).
Here is the AJAX code:
function respondToSelect(event)
{
new Ajax.Updater("memberSelect",
"/chainedSelect/family/updateSelect",
{method:'get', parameters: {selectedValue : $F("familySelect")} }
);
}
Here is the Grails method:
def updateSelect = {
def familySelected = Family.find("from Family as family where family.surname=:surname", [surname:params.selectedValue])
render (template:"selectMember", model : ['familySelected' : familySelected])
}
If someone could just explain what the third parameter of the AJAX function is doing I think I can figure the Grails part out.
{method:'get', parameters: {selectedValue : $F("account")}}
If someone could just explain what the third parameter of the AJAX
function is doing
The third argument is an object of parameters that get passed to the Updater that tell it how to make the HTTP request to the server.
Make the request an HTTP GET request:
method:'get'
Pass the following named query parameters:
{selectedValue: $F("account")}
$F is a prototype shortcut to retrieve the value of an element. In this case, it's getting the selected value of the DOM element with id account.
This ultimately results in something like the following request:
GET /chainedSelect/family/updateSelect?selectedValue=someValue
Where "someValue" is the currently-selected item in the "account" select list.