Closed calevans closed 6 years ago
Adrian, it won't let me comment on your comment above so I'll comment down here. I think we need both. The traditional way to organize API docs is by endpoint and I think for many readers, this is the expected norm. My format can most certainly be done better, it's barely MVP.
Going forward, I would like to also write docs based around tasks like you suggested. I would also like to have tutorials on common uses. For example, spin up a WordPress cloud account, and then us wp-cli to configure the blog and make the first post, all from a script. I'm sure there are better ones to use, that one is off the top of my head.
Thanks for the feedback.
Any thoughts on organizing docs around actions, rather than an endpoint+verb tree? for example,
Cloud Account
List Your Cloud Accounts
To retrieve a list of all the cloud accounts associated with an account make a call to
/cloud-account
with your API key.Endpoint:
/cloud-account
Method: GETExample
This will return a very verbose JSON payload …
Show Cloud Account Details
To retrieve the details of a specific cloud account, …
Endpoint:
/cloud-account/<ACCOUNT_ID>
Method: GETExample
This will return a similar payload to the first GET but it will be limited to a single cloud_account …
Create A New Cloud Account
To create a new Cloud Account …
Endpoint:
/cloud-account
Method: POSTExample etc…