API Documentation

[mikemilano]

I think functionality is probably the priority now, but it would be helpful to contributors & consumers if the API was documented well.

Even if the intent is to approach this in another rev of the API, it would be helpful to have a little more info.

For example, here are just a couple questions that come up when looking at the API:

• delete user: who can be deleted by the logged in user?, does this get deleted from pantheon entirely?
• get user info: is this restricted to the current user? if not, who's info can the logged in user access?
• check user's email by email? huhwhat? :)
• behind the api, is there a difference in how a profile is update with push vs patch?

Eventual API documentation would have these for each call:

• detailed descriptions
• example request
• example response
• error response

[jwshea]

:+1:

[mikemilano]

I've been wanting to test apiary.io for a while, and this was a good case to test it with. Their editor is pretty awesome, the documentation format is great, and it seems to provide for a solid collaboration platform for documenting APIs.

I haven't tried it, but it looks like they have tools on github so you don't have to host the docs with them as well.

http://docs.terminus.apiary.io/

I started some documentation there. It's a little tricky since the API isn't entirely restful with the path in a query string, but I think it will work.

I sent editor invites to Josh & Jon in case it's an option for documenting this API.

[joshkoenig]

Sweet! I think this would be a good call, and we're Heavybit siblings with Apiari, so we've got a good pipeline for feature suggestions and inside info. ;)

[patcon]

:+1: @mikemilano

[mikemilano]

Heavybit has some awesome companies listed, and Pantheon is right next to Apiary :) Stripe is there too, which is one of the best and well documented API's I've worked with.

I'll use this thread to identify questions that I've had, or have ended up figuring out, so the obvious items that should be documented are identified.

• What does validate_key() validate against. I'm thinking it validates that the key hasn't already been used for the current user, but maybe it also validates that the string is a valid format.
• What user profile attributes can be set vs which are read only
• What site attributes can be set vs which are read only (get/set_attribute(s))