search

nexcess / nexcess-api-docs

6 stars 8 forks source link

Introduction #1

Closed calevans closed 6 years ago

adrian-enspired commented 6 years ago

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: GET

Example

curl -v '__URL__/cloud-account' \
  -H 'Authorization: Bearer YOU_VERY_LONG_API_KEY_GOES_HERE' \
  -H 'Accept: application/json'

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: GET

Example

curl -v '__URL__/cloud-account/CLOUD_ID' \
  -H 'Authorization: Bearer YOU_VERY_LONG_API_KEY_GOES_HERE' \
  -H 'Accept: application/json'

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: POST

Example etc…

calevans commented 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.