Docs WTF?

[fireproofsocks]

As a developer, I would expect API documentation to include at a minimum a list of endpoints and HTTP verbs. I see none of that on this repo. As such, it fails in its primary purpose. The examples? Nothing but YAML files. What are these YAML files and what do they tell me about theGrid's API? Nothing. You have JSON Schema? Wonderful! But there's only one (?) and there's zero relevant information as to how data in the structure described by this schema fits into the API.... is that describing a request format? Is it a response format? If so, which one? In other words, the basic litmus test here fails: I expected to find something usable describing the API, but instead there is this mysterious collection of documents that I wouldn't think had anything to do with an API if that were not present in the title.

Small note re the link to the JSON Schema site, it must be http, not https: http://json-schema.org/

I'm sure you guys have worked very hard on the architecture of the services and on your app. I know writing docs can be difficult and time-consuming, but I would encourage you to put a commensurate amount of thought and effort into these API docs, otherwise we the developers cannot make use of any of your labors.

[jonnor]

Hello. This repository contains the source for the API documentation. Did you have a look at the output, hosted at https://developer.thegrid.io ? There you will find the list of endpoints and methods, for instance most of the API related to content and sites is here: https://developer.thegrid.io/api.html

[fireproofsocks]

The comment was directed at https://developer.thegrid.io/ specifically -- that page is more or less useless from an API perspective for the reasons stated in the original post.

https://developer.thegrid.io/api.html is what I was after, thank you.

I would consider this issue if the https://developer.thegrid.io/ page were refactored to prominently link to the https://developer.thegrid.io/api.html page (e.g. use a left-menu title for "Endpoints" or similar) since that is ultimately what visitors are expecting to see on a page titled "The Grid API". Or, preferably, have the api.html live at the https://developer.thegrid.io/ page and have the current page on a sub-page that is geared more for introductory talk about the api.

I would open a pull request for this type of change, but I don't see a CONTRIBUTING.md file that would explain whatever system is used to render the docs.

[jonnor]

Glad you found what you wanted.

The link in question was second one from the top. I added a header to the secion, so it gets a left-menu entry now. Also reduced the amount of fluff on frontpage a bit, hopefully making things easier to find.

Missing contribution docs tracked here: #89