Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clean-up some text around our status codes #178

Merged
merged 1 commit into from
Jun 6, 2017

Conversation

duglin
Copy link
Contributor

@duglin duglin commented May 3, 2017

Follow-on to this comment: https://github.com/openservicebrokerapi/servicebroker/pull/166/files#r113097103

Changes:

  • Add MUSTs/MAYs on each status code in the tables
  • Add a 404 as the more appropriate response after a DELETE, not 410
  • Allow for a 200 in spots where it was missing
  • Clarify things, like when a conflict happens
  • lots of typographical changes (spaces, wrong casing, etc...) - nits

Signed-off-by: Doug Davis [email protected]

@cfdreddbot
Copy link

Hey duglin!

Thanks for submitting this pull request! I'm here to inform the recipients of the pull request that you and the commit authors have already signed the CLA.

spec.md Outdated
|---|---|---|
| accepts_incomplete | boolean | A value of true indicates that the marketplace and its clients support asynchronous broker operations. If this parameter is not included in the request, and the broker can only provision an instance of the requested plan asynchronously, the broker should reject the request with a 422 as described below. |
| accepts_incomplete | boolean | A value of true indicates that the marketplace and its clients support asynchronous broker operations. If this parameter is not included in the request, and the broker can only provision an instance of the requested plan asynchronously, the broker should reject the request with a 422 as described below. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be "the broker should reject the request with a 422 Unprocessable Entity as described below" for consistency?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

probably. As you mentioned below there are quite a few spots where we just use the number and not the text, but let me see if I can find them all.

spec.md Outdated
| 422 Unprocessable Entity | MUST be returned if the broker only supports asynchronous provisioning for the requested plan and the request did not include <code>?accepts_incomplete=true</code>. The expected response body is: <code>{ "error": "AsyncRequired", "description": "This service plan requires client support for asynchronous service operations." }</code>, as described below. |
| 200 OK | MUST be returned if the service instance already exists, is fully provisioned, and the requested parameters are identical to the existing service instance. The expected response body is below. |
| 201 Created | MUST be returned if the service instance was provisioned as a result of this request. The expected response body is below. |
| 202 Accepted | MUST be returned if the service instance provisioning is in progress. This triggers the platform marketplace to poll the [Service Instance Last Operation Endpoint](#polling) for operation status. Note that a resent `PUT` request MUST return a 202, not a 200, if the service instance is not yet fully provisioned. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment as above.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

spec.md Outdated
| 422 Unprocessable entity | MUST be returned if the requested change is not supported or if the request cannot currently be fulfilled due to the state of the instance (e.g. instance utilization is over the quota of the requested plan). Broker SHOULD include a user-facing message in the body; for details see [Broker Errors](#broker-errors). Additionally, a 422 can also be returned if the broker only supports asynchronous update for the requested plan and the request did not include <code>?accepts_incomplete=true</code>; in this case the expected response body is: <code>{ "error": "AsyncRequired", "description": "This service plan requires client support for asynchronous service operations." }</code> |
| 200 OK | MUST be returned if the request's changes have been applied. The expected response body is <code>{}</code>. |
| 202 Accepted | MUST be returned if the service instance update is in progress. This triggers the platform marketplace to poll the [Service Instance Last Operation Endpoint](#polling) for operation status. Note that a resent `PATCH` request MUST return a 202, not a 200, if the requested update has not yet completed. |
| 422 Unprocessable entity | MUST be returned if the requested change is not supported or if the request cannot currently be fulfilled due to the state of the instance (e.g. instance utilization is over the quota of the requested plan). Broker SHOULD include a user-facing message in the body; for details see [Broker Errors](#broker-errors). Additionally, a 422 can also be returned if the broker only supports asynchronous update for the requested plan and the request did not include <code>?accepts_incomplete=true</code>; in this case the expected response body is: <code>{ "error": "AsyncRequired", "description": "This service plan requires client support for asynchronous service operations." }</code> |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like there are lots of places. Maybe it's OK to ignore!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

spec.md Outdated
| 422 Unprocessable Entity | MUST be returned if the broker requires that <code>app_guid</code> be included in the request body. The expected response body is: <code>{ "error": "RequiresApp", "description": "This service supports generation of credentials through binding an application only." }</code> |
| 200 OK | MUST be returned if the binding already exists and the requested parameters are identical to the existing binding. The expected response body is below. |
| 201 Created | MUST be returned if the binding was created as a result of this request. The expected response body is below. |
| 409 Conflict | MUST be returned if a service binding with the same id, for the same service instance, already exists but with different parameters. The expected response body is <code>{}</code>, though the description field MAY be used to return a user-facing error message, as described in [Broker Errors](#broker-errors). |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Regarding the 409 Conflict, should we say "but with different parameters"? I'd imagine that the conflict error should be returned if you try to create a binding for the same service instance with an existing binding ID regardless of parameters?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My assumption is that all of the APIs in the spec are meant to be idempotent, in which case returning an error on the 2nd try violates that. Also, if the first response message is lost, which is why they're resending the request, if we return a 409 how will the client recover? I think that goes back to the idempotent nature of things. This also relates to another discussion we're having about how long, or if at all, a broker needs to hold on to the credentials for a binding. I know some people have said that brokers might be stateless but that seems a bit odd in the case of credentials since they need to hold on to them so they can verify that apps are using the right ones, right? So, if they have to hang on to them to so auth checking then is it really a burden to ask them to use them to replay a binding response message?

But, if my assumption is wrong about them being idempotent then we may need to look at all of the APIs to make sure we have a clear recovery plan for each when messages are lost.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interested to hear what @shalako thinks on this point.

I think the spec was intending to give flexibility to brokers that may not be able to replay requests for some reason.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@duglin I spoke to a few of the CF service teams about holding onto credentials. It seems that most brokers are stateless and whatever downstream component they talk to give them credentials when they create a new binding (synchronously) which they immediately return to the platform. There isn't currently a way for brokers to ask whatever is downstream to give them the credentials again for a particular binding. I'm not saying this is the right way, but I think that's what today's world looks like.

spec.md Outdated
| operation | string | A broker-provided identifier for the operation. When a value for <code>operation</code> is included with asynchronous responses for [Provision](#provisioning), [Update](#updating_service_instance), and [Deprovision](#deprovisioning) requests, the broker client SHOULD provide the same value using this query parameter as a URL-encoded string. |
| service_id | string | ID of the service from the catalog. |
| plan_id | string | ID of the plan from the catalog. |
| operation | string | A broker-provided identifier for the operation. When a value for <code>operation</code> is included with asynchronous responses for [Provision](#provisioning), [Update](#updating_service_instance), and [Deprovision](#deprovisioning) requests, the broker client SHOULD provide the same value using this query parameter as a URL-encoded string. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SHOULD for operation (the broker client SHOULD) is being changed to MUST in another PR, I assume it's going to get changed here as a merge?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yup - doing the rebase now and its picking up the MUST

@duglin
Copy link
Contributor Author

duglin commented May 8, 2017

rebased

LGTM

Approved with PullApprove

@angarg12
Copy link
Contributor

angarg12 commented May 9, 2017

LGTM

Approved with PullApprove

1 similar comment
@avade
Copy link
Contributor

avade commented May 9, 2017

LGTM

Approved with PullApprove

@angarg12
Copy link
Contributor

angarg12 commented May 9, 2017

Looks like it needs rebasing.

@duglin
Copy link
Contributor Author

duglin commented May 9, 2017

rebased

@angarg12
Copy link
Contributor

angarg12 commented May 9, 2017

lgtm

Approved with PullApprove

@duglin
Copy link
Contributor Author

duglin commented May 9, 2017

ping @avade @vaikas-google @pmorie for some LGTMs

Approved with PullApprove

@avade
Copy link
Contributor

avade commented May 10, 2017

LGTM

Approved with PullApprove

@duglin
Copy link
Contributor Author

duglin commented May 11, 2017

rebased

@angarg12
Copy link
Contributor

angarg12 commented May 12, 2017

Looks like your script is already giving results 😄

tools/../spec.md: Can't find section '#route_services' in tools/../spec.md
tools/../spec.md - 443: Use 'SHOULD'

@duglin
Copy link
Contributor Author

duglin commented May 12, 2017

nice! :-)
fixed - I messed up on the rebase. Would be so much easier with shorter lines.

@angarg12
Copy link
Contributor

angarg12 commented May 12, 2017

LGTM

Approved with PullApprove

@mattmcneeney
Copy link
Contributor

@duglin we can cut all of the lines to 80 characters and add a travis check in the #192 PR if you'd like.

@duglin
Copy link
Contributor Author

duglin commented May 12, 2017

I would love that :-) I'll add comments there (later today) of other syntax changes that we should make, or that I've made in other PRs (that I can pull out).

Question is... do we merge #192 before or after the other current PRs? :-) While it might cause a ton of rebases (especially for me), it would make it easier to review those other PRs if #192 went in first.

@mattmcneeney
Copy link
Contributor

@duglin Whilst #192 would mean other PRs need a rebase, the rebases should typically be fairly small as long as the PR is only touching a small bit of the spec. Some fixes that people (ie. me) had bundled into other PRs when they spotted them have been pulled into #192 so it should ensure the other PRs are cleaner too.

I'm probably biased (I've been rebasing the PR on each change which isn't the best job) but I think it's sensible enough for merge it soon. But happy with whatever everyone else would like.

@duglin
Copy link
Contributor Author

duglin commented May 23, 2017

rebase

@avade avade modified the milestone: 2.12 May 24, 2017
@duglin
Copy link
Contributor Author

duglin commented May 28, 2017

ready for review

spec.md Outdated
| 410 Gone | Appropriate only for asynchronous delete operations. The platform MUST consider this response a success and remove the resource from its database. The expected response body is `{}`. Returning this while the platform is polling for create or update operations SHOULD be interpreted as an invalid response and the platform SHOULD continue polling. |
| 200 OK | MUST be returned upon successful processing of this request. The expected response body is below. |
| 404 Not Found | MUST be returned if the service instance does not exist. |
| 410 Gone | MAY be returned if the broker knows about the service instance but it had been previously deleted. Appropriate only for asynchronous delete operations. The platform MUST consider this response a success and remove the resource from its database. The expected response body is `{}`. Returning this while the platform is polling for create or update operations SHOULD be interpreted as an invalid response and the platform SHOULD continue polling. While a `410 Gone` is allowed, the RECOMMENDED response is `404 Not Found`. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mattmcneeney / @zrob does CF already conform to this flow?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For async delete operations, brokers must return a 410. For async create and update, brokers must return a 200. If the resource does not exist, brokers must return a 410.

A 404 is problematic because it may be temporarily returned by a intermediating component (e.g. the CF router). We would not want a platform to remove a resource from its database as a result of a 404 response, since we cannot guarantee that a 404 was returned by the broker itself.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this feels like we're letting an impl detail bleed into the spec and, sort of, reinventing http response codes in the process. Can we discuss this on the next call?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agree with @shalako that this is a change to the spec, not appropriate for a PR titled clean-up text

perhaps a separate issue should be raised around what status codes should be supported. as is, this change potentially invalidates existing broker and platform implementations

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll move this to a new issue since I think more discussions are needed.

@avade
Copy link
Contributor

avade commented May 30, 2017

LGTM

Approved with PullApprove

@duglin
Copy link
Contributor Author

duglin commented May 31, 2017

rebased again

@vaikas
Copy link
Contributor

vaikas commented May 31, 2017

LGTM

Approved with PullApprove

2 similar comments
@avade
Copy link
Contributor

avade commented Jun 1, 2017

LGTM

Approved with PullApprove

@angarg12
Copy link
Contributor

angarg12 commented Jun 2, 2017

LGTM

Approved with PullApprove

spec.md Outdated
| previous_values.service_id | string | ID of the service for the instance. |
| previous_values.plan_id | string | ID of the plan prior to the update. |
| previous_values.organization_id | string | ID of the organization specified for the instance. |
| previous_values.space_id | string | ID of the space specified for the instance. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe the escaped underscores were required to prevent the CF docs from styling characters between them as italic.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The escape char as been removed in other spots (I think by Matt) so this is just following that pattern. Notice like 449 doesn't have it. Or is there something special about these lines that makes it required here? @mattmcneeney ?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If it was remove elsewhere, it may be breaking CF docs. Members of this group who are involved with the CF community must consider themselves custodians of the CF broker docs, and consider impact when making nitpick changes.

That said, it is possible that @mattmcneeney has discussed the topic with the CF docs team and confirmed that removal of the escape char no longer causes a change in styling.

spec.md Outdated
| 410 Gone | MUST be returned if the binding does not exist. The expected response body is `{}`. |
| 200 OK | MUST be returned if the binding was deleted as a result of this request. The expected response body is `{}`. |
| 404 Not Found | MUST be returned if the service binding does not exist. |
| 410 Gone | MAY be returned if the binding is known to the service broker but had been previously deleted. The expected response body is `{}`. While a `410 Gone` is allowed, the RECOMMENDED response is `404 Not Found`. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since a 404 may be temporarily returned by an intermediating component, we wouldn't want the platform to execute a state change based on it. Only 200 and 410 should be supported responses.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

reverting for now and we can discuss later - see previous comment on this

spec.md Outdated
| 200 OK | MUST be returned if the service instance was deleted as a result of this request. The expected response body is `{}`. |
| 202 Accepted | MUST be returned if the service instance deletion is in progress. This triggers the marketplace to poll the [Service Instance Last Operation Endpoint](#polling-last-operation) for operation status. Note that a resent `DELETE` request MUST return a `202 Accepted`, not a `200 OK`, if the delete request has not completed yet. |
| 404 Not Found | MUST be returned if the service instance does not exist. |
| 410 Gone | MAY be returned if the service instance is known to the broker but had been previously deleted. The expected response body is `{}`. While a `410 Gone` is allowed, the RECOMMENDED response is `404 Not Found`. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same issues with 404. We should not introduce this as a supported response without further discussion.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

reverting for now

@shalako
Copy link
Contributor

shalako commented Jun 2, 2017

@duglin we can cut all of the lines to 80 characters and add a travis check in the #192 PR if you'd like.

Please don't cut all lines. Soft wrap is your friend.

@mattmcneeney
Copy link
Contributor

mattmcneeney commented Jun 2, 2017 via email

spec.md Outdated
@@ -387,16 +388,15 @@ $ curl http://username:password@broker-url/v2/service_instances/:instance_id?acc
}' -X PUT -H "X-Broker-API-Version: 2.11" -H "Content-Type: application/json"
```

### Response
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

was removing this heading accidental?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

geez, not sure how I did this - thanks

spec.md Outdated
| 200 OK | The requested changes have been applied. The expected response body is `{}`. |
| 202 Accepted | Service instance update is in progress. This triggers the platform marketplace to poll the [Last Operation](#polling-last-operation) endpoint for operation status. |
| 200 OK | MUST be returned if the request's changes have been applied. The expected response body is `{}`. |
| 202 Accepted | MUST be returned if the service instance update is in progress. This triggers the platform marketplace to poll the [Last Operation](#polling-last-operation) for operation status. Note that a resent `PATCH` request MUST return a `202 Accepted`, not a `200 OK`, if the requested update has not yet completed. |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

resent -> re-sent

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done - and in the other spots too

spec.md Outdated
| 200 OK | MAY be returned if the service instance already exists and the requested parameters are identical to the existing service instance. The expected response body is below. |
| 202 Accepted | Service instance provisioning is in progress. This triggers the platform marketplace to poll the [Last Operation](#polling-last-operation) endpoint for operation status. |
|---|---|
| 200 OK | MUST be returned if the service instance already exists, is fully provisioned, and the requested parameters are identical to the existing service instance. The expected response body is below. |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A change from MAY to MUST feels like a spec change rather than a text fix. It looks like the intent is that 201 can be returned in the case the service instance already existed. Are we concerned with enforcing a change here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since PUT is supposed to be idempotent, I was trying to distinguish between "already there", "completed as a result of this request" and "doing it asynchronously" as the platform may want to know what happened on this particular request. IMO, the old wording implies what the new text says - just not as clearly.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @duglin on this matter. MAY is also significantly less useful (ie, not useful at all) compared to MUST here.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that MUST clarifies things here, because what else would you return, as there is only one conditional that can trigger this case.

@duglin duglin mentioned this pull request Jun 4, 2017
@duglin duglin force-pushed the clarify202 branch 2 times, most recently from a338bb0 to 0b055a1 Compare June 4, 2017 22:33
Copy link
Contributor

@pmorie pmorie left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some nits, generally LGTM

spec.md Outdated
| 200 OK | MAY be returned if the service instance already exists and the requested parameters are identical to the existing service instance. The expected response body is below. |
| 202 Accepted | Service instance provisioning is in progress. This triggers the platform marketplace to poll the [Last Operation](#polling-last-operation) endpoint for operation status. |
|---|---|
| 200 OK | MUST be returned if the service instance already exists, is fully provisioned, and the requested parameters are identical to the existing service instance. The expected response body is below. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @duglin on this matter. MAY is also significantly less useful (ie, not useful at all) compared to MUST here.

spec.md Outdated
| 409 Conflict | MUST be returned if a service instance with the same id already exists but with different attributes. The expected response body is `{}`. |
| 422 Unprocessable Entity | MUST be returned if the broker only supports asynchronous provisioning for the requested plan and the request did not include `?accepts_incomplete=true`. The expected response body is: `{ "error": "AsyncRequired", "description": "This service plan requires client support for asynchronous service operations." }`, as described below. |


Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

spurious newline?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

removed

spec.md Outdated
|---|---|
| 200 OK | MUST be returned if the service instance already exists, is fully provisioned, and the requested parameters are identical to the existing service instance. The expected response body is below. |
| 201 Created | MUST be returned if the service instance was provisioned as a result of this request. The expected response body is below. |
| 202 Accepted | MUST be returned if the service instance provisioning is in progress. This triggers the platform marketplace to poll the [Service Instance Last Operation Endpoint](#polling-last-operation) for operation status. Note that a re-sent `PUT` request MUST return a `202 Accepted`, not a `200 OK`, if the service instance is not yet fully provisioned. |
| 409 Conflict | MUST be returned if a service instance with the same id already exists but with different attributes. The expected response body is `{}`. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should have the same guidance as we have elsewhere for conflicts - that user-facing errors may be supplied

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

Follow-on to this comment: https://github.com/openservicebrokerapi/servicebroker/pull/166/files#r113097103

Changes:
- Add MUSTs/MAYs on each status code in the tables
- Add a 404 as the more appropriate response after a DELETE, not 410
- Allow for a 200 in spots where it was missing
- lots of typographical changes (spaces, wrong casing, etc...) - nits

Signed-off-by: Doug Davis <[email protected]>
@shalako
Copy link
Contributor

shalako commented Jun 6, 2017

LGTM

Approved with PullApprove

1 similar comment
@avade
Copy link
Contributor

avade commented Jun 6, 2017

LGTM

Approved with PullApprove

@vaikas
Copy link
Contributor

vaikas commented Jun 6, 2017

LGTM

Approved with PullApprove

@zrob
Copy link
Member

zrob commented Jun 6, 2017

LGTM

Approved with PullApprove

@avade avade merged commit 3bbb81c into openservicebrokerapi:master Jun 6, 2017
@duglin duglin deleted the clarify202 branch June 7, 2017 19:58
@pmorie pmorie mentioned this pull request Jun 13, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

9 participants