search

CircleCI-Archived / api-preview-docs

In-progress docs about the pre-release preview of CircleCI API v2
72 stars 39 forks source link

Consistent URL pluralisation #50

Closed robcresswell closed 4 years ago

robcresswell commented 4 years ago

There's a few oddities with resource naming in the URLs, alternating between singular and plurals. This is minor, but annoying when trying to build clients against the API.

For example:

# Retrieve a list of Pipelines
GET /project/:project_slug/pipeline/
# Retrieve a list of Jobs
GET /workflow/:id/jobs

Generally speaking, REST uses pluralised resources for the base i.e.

# Retrieve a list of workflows
GET workflows
# Retrieve a single workflow
GET workflows/:id

Is there any plan to follow standards here, or at be consistent within your own definitions?

jama22 commented 4 years ago

Hi @robcresswell , sorry for the delayed response. The short answer is..yes, we do! We've announced that as one of the changes we'll be making in our proposed breaking changes https://github.com/CircleCI-Public/api-preview-docs/blob/master/docs/breaking.md

robcresswell commented 4 years ago

No worries, thanks for getting back to me @jama22! Breaking change doc looks great; I'll close this.