-
Notifications
You must be signed in to change notification settings - Fork 433
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
Conversation
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. | |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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. | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Same comment as above.
There was a problem hiding this comment.
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> | |
There was a problem hiding this comment.
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!
There was a problem hiding this comment.
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). | |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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. | |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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
1 similar comment
Looks like it needs rebasing. |
rebased |
rebased |
Looks like your script is already giving results 😄
|
nice! :-) |
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. |
@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. |
rebase |
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`. | |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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.
rebased again |
2 similar comments
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. | |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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 ?
There was a problem hiding this comment.
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`. | |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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`. | |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
reverting for now
I haven't spoken to the docs team, so maybe I shouldn't have removed the
underscores. I'll check this and re-escape them if necessary.
…On Fri, 2 Jun 2017 at 18:49, Shannon Coen ***@***.***> wrote:
@duglin <https://github.com/duglin> we can cut all of the lines to 80
characters and add a travis check in the #192
<#192> PR if
you'd like.
Please don't cut all lines. Soft wrap is your friend.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#178 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AG7UzHpwVDClxFQYOjBjvSzYSA4kuv3Dks5sAEsrgaJpZM4NPfVf>
.
|
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 |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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. | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
resent -> re-sent
There was a problem hiding this comment.
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. | |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
a338bb0
to
0b055a1
Compare
There was a problem hiding this 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. | |
There was a problem hiding this comment.
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. | | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
spurious newline?
There was a problem hiding this comment.
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 `{}`. | |
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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]>
Follow-on to this comment: https://github.com/openservicebrokerapi/servicebroker/pull/166/files#r113097103
Changes:
Signed-off-by: Doug Davis [email protected]