Create an advanced API Blueprint tutorial

[danielgtaylor]

This (draft) creates a new advanced API Blueprint tutorial covering JSON Schema, request and response attributes, data structures and relation types.

I'm pretty unsure of the relation types section, so please have a look and give me any feedback. Once this is ready, I'm thinking of making available a final full example .apib file with these features and linking the tutorial to the advanced tutorial somehow.

Feedback will be much appreciated!

[pksunkara]

Can we just have 2 choices here? We don't need as many. We should try to make the Tutorials as small as possible

[danielgtaylor]

This was copied directly from the first tutorial, but I can make it have fewer choices if it helps.

[pksunkara]

Looks good. Haven't checked closely for grammar issues.

[kylef]

This tutorial produces a large JSON Schema, I wonder if we would be better off describing a simpler structure, perhaps the structure used on creating a question instead:

+ Request (application/json)
    + Body

            {
              "question": "Favourite language?"
              "choices": [ "Swift", "Objective-C" ]
            }

    + Schema

            {
              "$schema": "http://json-schema.org/draft-04/schema#",
              "type": "object",
              "properties": {
                "question": { "type": "string }
                "choices": {
                  "type": "array",
                  "items": { "type": "string" },
                  "minItems": 2
                }
              }
            }

[pksunkara]

I agree with @kylef

[danielgtaylor]

@kylef @pksunkara I think I have addressed all of the feedback. Please take another look!

I'll also look into the highlighting bugs soon, but that will be a different task.

[pksunkara]

The below example is not taken from API Blueprint tutorial.

[danielgtaylor]

@pksunkara addressed feedback. Thanks!

[pksunkara]

Isn't List All Questions part of Question Collection resource?

[danielgtaylor]

More feedback addressed. I can't seem to fix the syntax highlighting - it will need to be done along with a few other minor fixes in the syntax highlighter package. Will try and get to that soon, as it's quite annoying.

[zdne]

👍