https://github.com/cloudfoundry/brokerapi
A Go package for implementing the V2 Open Service Broker API
https://github.com/cloudfoundry/brokerapi
Last synced: 29 days ago
JSON representation
A Go package for implementing the V2 Open Service Broker API
- Host: GitHub
- URL: https://github.com/cloudfoundry/brokerapi
- Owner: cloudfoundry
- License: apache-2.0
- Created: 2014-05-16T10:07:19.000Z (almost 12 years ago)
- Default Branch: main
- Last Pushed: 2025-03-13T19:15:45.000Z (about 1 year ago)
- Last Synced: 2025-03-18T09:21:52.669Z (about 1 year ago)
- Language: Go
- Homepage:
- Size: 3.18 MB
- Stars: 86
- Watchers: 78
- Forks: 71
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE-OF-CONDUCT.md
Awesome Lists containing this project
README
# brokerapi
[](https://github.com/cloudfoundry/brokerapi/actions/workflows/run-tests.yml?query=branch%3Amain)
A Go package for building [V2 Open Service Broker API](https://github.com/openservicebrokerapi/servicebroker/) compliant Service Brokers.
## [Docs](https://godoc.org/code.cloudfoundry.org/brokerapi/v13)
## Dependencies
- Go
- GNU Make 3.81
## Contributing
We appreciate and welcome open source contribution. We will try to review the changes as soon as we can.
## Usage
`brokerapi` defines a
[`ServiceBroker`](https://godoc.org/code.cloudfoundry.org/brokerapi/v13/domain#ServiceBroker/domain#ServiceBroker)
interface. Pass an implementation of this to
[`brokerapi.New`](https://godoc.org/code.cloudfoundry.org/brokerapi/v13#New),
which returns an `http.Handler` that you can use to serve handle HTTP requests.
## Error types
`brokerapi` defines a handful of error types in `service_broker.go` for some
common error cases that your service broker may encounter. Return these from
your `ServiceBroker` methods where appropriate, and `brokerapi` will do the
"right thing" (™), and give Cloud Foundry an appropriate status code, as per
the [Service Broker API
specification](https://docs.cloudfoundry.org/services/api.html).
### Custom Errors
`NewFailureResponse()` allows you to return a custom error from any of the
`ServiceBroker` interface methods which return an error. Within this you must
define an error, a HTTP response status code and a logging key. You can also
use the `NewFailureResponseBuilder()` to add a custom `Error:` value in the
response, or indicate that the broker should return an empty response rather
than the error message.
## Request Context
When provisioning a service `brokerapi` validates the `service_id` and `plan_id`
in the request, attaching the found instances to the request Context. These
values can be retrieved in a `brokerapi.ServiceBroker` implementation using
utility methods `RetrieveServiceFromContext` and `RetrieveServicePlanFromContext`
as shown below.
```go
func (sb *ServiceBrokerImplementation) Provision(ctx context.Context,
instanceID string, details brokerapi.ProvisionDetails, asyncAllowed bool) {
service := brokerapi.RetrieveServiceFromContext(ctx)
if service == nil {
// Lookup service
}
// [..]
}
```
## Originating Identity
The request context for every request contains the unparsed
`X-Broker-API-Originating-Identity` header under the key
`originatingIdentity`. More details on how the Open Service Broker API
manages request originating identity is available
[here](https://github.com/openservicebrokerapi/servicebroker/blob/master/spec.md#originating-identity).
## Request Identity
The request context for every request contains the unparsed
`X-Broker-API-Request-Identity` header under the key
`requestIdentity`. More details on how the Open Service Broker API
manages request originating identity is available
[here](https://github.com/openservicebrokerapi/servicebroker/blob/master/spec.md#request-identity).
## Example Service Broker
You can see the
[cf-redis](https://github.com/pivotal-cf/cf-redis-broker/blob/2f0e9a8ebb1012a9be74bbef2d411b0b3b60352f/broker/broker.go)
service broker uses the BrokerAPI package to create a service broker for Redis.
## Releasing
Releasing steps can be found [here](https://github.com/cloudfoundry/brokerapi/wiki/Releasing-new-BrokerAPI-major-version)