Spacex-api: Add API description

[honzajavorek]

It would be nice to provide the API description in one of the API description formats, such as the API Blueprint (actually Markdown-based, so not that far from what you have now) or the OpenAPI.

[jakewmeyer]

API blueprint looks awesome! Been wanting a good standardized format for the docs 👍

Might look more into OpenAPI instead though, since Oracle owns Apiary and thus API blueprint.

[paraskakis]

Technically Oracle "owns" API Blueprint as much as it "owns" OpenAPI ;)
Both are open source, both are public specs. Apiary (and Oracle) are invested in both equally.
Choice is up to you, how usable you find each format and what tooling you might want to use from each ecosystem. One great way to verify that your API Description (and thus documentation) matches a specific API implementation is http://dredd.org/en/latest/ - open source testing tool you can use.
I'd be happy to review any API description you put up.

[jakewmeyer]

Fair enough, I'll get started on converting the docs over 👍

[amorriscode]

@jakewmeyer Would you like any help on this? I'd love to be involved in this project somehow. :)

[codenirvana]

@jakewmeyer I feel in addition to the current documentation, having a Postman Collection will help to access this more easily.
It allows API Documentation, Categorised Folders, Saved Examples and more.

[jakewmeyer]

Absolutely open to having multiple formats/standards available @codenirvana
Would you be willing to help document it?

@amorriscode Definitely need help creating the api-blueprint version of the docs, juggling a few other feature requests currently.

[amorriscode]

@jakewmeyer I have the day off tomorrow so I will tackle this then! I'm going to use the API Blueprint if that's okay with you. 👍

[jakewmeyer]

Links should be fixed by #137

[amorriscode]

Whoops, sorry about that!

[jakewmeyer]

No worries 👍