How does one know if markdown is in Blueprint API format?

[streamich]

How does one know if markdown is in Blueprint API format? For example, say I have an incoming markdown file. If the file is in Bluepring API format I should render it as and API, otherwise I render it as a standard Markdown HTML. But how do I know if the markdown is in Blueprint API format?

[jrep]

How does one know if markdown is in Blueprint API format? For example, say I have an incoming markdown file. If the file is in Bluepring API format I should render it as and API, otherwise I render it as a standard Markdown HTML. But how do I know if the markdown is in Blueprint API format?

If the first line is "FORMAT: 1A" or similar, then it's Apiary Blueprint. That is, the Blueprint language allows this, but does not define any semantics for it. The Apiary web application does define semantics (and even the set of supported format names, like "1A"). The FORMAT line is meaningful only to Apiary. I'm not sure whether it's actually required, but perhaps you can impose that requirement on your authors.

Of course, if you're doing something non-Apiary with your Blueprint, this may not help.

Jack Repenning Jack@netgate.net

[pksunkara]

@streamich We try to parse the incoming markdown file and generate the API Blueprint AST assuming that the given file is an API Blueprint file. You can probably look at the generated AST and guess if a file is an API Blueprint or not. But it is not always deterministic since the normal markdown file can use API Blueprint keywords. Other than that, there are no ways to identify a API Blueprint file.

Please remember that, every API Blueprint file is a markdown file where as not every markdown file is an API Blueprint file.

[zdne]

But how do I know if the markdown is in Blueprint API format?

You can't really. Similarly as you can't distinguish plain text from markdown. The only way is to get the metadata (e.g. Content-Type) with the file.

In the case of Content-Type or Accept HTTP headers the value for API Blueprint Markdown should be text/vnd.apiblueprint+markdown.

[zdne]

Note the FORMAT: 1A is Apiary-specific metadata and it is not required in API blueprints outside of Apiary. In a future it will be removed from Apiary as well, so I wouldn't really rely on it.

[streamich]

May API blueprints should have their file extensions? Like minified JS files have .min.js, API blueprints could be something like .api.md.

[zdne]

We are using .apib at Apiary. But I like the .api.md as well – this allows you to benefit from GitHub rendering of markdown files. So while we are using apib I would say sticking with api.md is a good alternative.

[zdne]

To wrap up this issue – the correct approach is to look at the file media type – it should be text/vnd.apiblueprint+markdown for every API Blueprint version to-date.

Please reopen if a further clarification is needed.