Skip to content
This repository has been archived by the owner on Nov 8, 2024. It is now read-only.

Create an advanced API Blueprint tutorial #279

Merged
merged 1 commit into from
Nov 11, 2015

Conversation

danielgtaylor
Copy link
Contributor

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!

@danielgtaylor danielgtaylor force-pushed the daniel/advanced-tutorial branch from 0b4228f to 90066ec Compare November 6, 2015 00:22
"choice": "Swift",
"url": "/questions/1/choices/1",
"votes": 2048
}, {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@pksunkara
Copy link
Contributor

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


+ Schema

{
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
                }
              }
            }

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @kylef

@danielgtaylor danielgtaylor force-pushed the daniel/advanced-tutorial branch 2 times, most recently from fcc271e to 3551977 Compare November 10, 2015 01:02
@danielgtaylor
Copy link
Contributor Author

@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.


Action request and response bodies can have associated schemas that describe the allowed structure of the body content. JSON bodies are typically described with [JSON Schema](http://json-schema.org/). Given a simple JSON response body we can describe the structure of the response with JSON Schema in a `+ Schema` section.

The schema can describe the type of each member, which members are required, default values, and support a number of other advanced features. Below is an example, taken from the API Blueprint tutorial blueprint:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The below example is not taken from API Blueprint tutorial.

@danielgtaylor danielgtaylor force-pushed the daniel/advanced-tutorial branch from 3551977 to 1f20f01 Compare November 10, 2015 23:27
@danielgtaylor
Copy link
Contributor Author

@pksunkara addressed feedback. Thanks!


Once you start using MSON, you may find yourself wanting to reuse certain commonly used or nested data structure components. This is possible with the `## Data Structures` section. Attributes sections can then reference the data structures defined in the Data Structures or other resource sections by name.

For example, using the polls API question resource, we can split out the `Question` and `Choice` objects:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@danielgtaylor danielgtaylor force-pushed the daniel/advanced-tutorial branch from 1f20f01 to 1614ff6 Compare November 11, 2015 20:18
@danielgtaylor
Copy link
Contributor Author

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.

pksunkara added a commit that referenced this pull request Nov 11, 2015
Create an advanced API Blueprint tutorial
@pksunkara pksunkara merged commit b51468d into master Nov 11, 2015
@pksunkara pksunkara deleted the daniel/advanced-tutorial branch November 11, 2015 21:19
@zdne
Copy link
Contributor

zdne commented Nov 12, 2015

👍

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants