How to reuse objects in schema of API BluePrint?

Question

I have created an API that delivers a resource named "Thumbnail" (/thumbnails)

{
    "name": "toto",
    "uri": "http://xxx"
}

In other hand I have multiple resources that includes that Thumbnail resource in them (like /articles, /videos ...):

{
    "name": "playlist",
    "thumbnail": 
    {
        "name": "toto",
        "uri": "http://xxx"
    }
}

When I write the schemas of those webservices in the BluePrint markdown, I would like to be able to reuse the schema that I've created for the Thumbnail schema in order to not repeat the code in the schemas. I've heart of the Trait feature ( https://github.com/apiaryio/api-blueprint/issues/47 ) but I don't know if it will fit my needs and if it works with aglio and dredd.

Do you know the best thing to do in my case?

Primp

Answer 1

You can use MSON in Attributes section of the API Blueprint to define reusable objects.

You can see some examples in here, here and here.

Wallache

Note, that getting these to render in Aglio currently requires you to use the beta release, which can be installed via npm install -g aglio@beta. Soon it will be released as version 2.0. – Roadability

And it is supported in dredd – Lillia

Hum, but can I use these attributes in the schema of my WS ? I like when Dredd make test on the schema. – Writing

Answer 2

So I have updated my dredd and tested MSON. It seems cool and efficient. I have just a problem with this md :

# Data Structures

## Video (object)
Definition of a video
+ id: 11111 (number) - The unique key
+ description: "my video" (string) - Free text of video
+ truc: "ffff" (string)

# Group VideosTest

## Videos List [/videos]
List of videos

### List of videos [GET]

+ Response 200 (application/json)

    + Attributes (array[Video])

The test doesnt fail, but I haven't attributes "truc" in my real API and I have an attribute URL. So I expected the test to fail. Am I wrong ?

Primp

Can you paste what your real API is expecting? – Wallache

[{"id": "1", "description": "desc", "url": "http://xxx"},{"id": "2", "description": "desc2", "url": "http://xxx"}} – Writing

Unfortunately, MSON doesn't support more than a single element in the array. :( – Wallache

I have the same problem with only a video, I answer and Post u the example – Writing

Answer 3

I give u example :

My md :

# Data Structures

## Video (object)
Definition of a video
    + id: 11111 (number, required) - The unique key
    + description: "my video" (string, required) - Free text of video
    + truc: "ffff" (string, required)

## A video [/videos/{id}]
See a video

+ Parameters

    + id (required, string, `a-la-decouverte-des-metiers-projection-du-film`) ... L'id ou le slug de la video

### Select a video [GET]

+ Response 200 (application/json)

    + Attributes (Video)

And my API :

{
"id": "1111",
"description": "description of the video",
"uri": "http://"
}

Test is OK, but I want an error by dredd !!!

Primp