├── .gitignore ├── .travis.yml ├── LICENSE ├── NOTICE ├── README.md ├── api.md ├── release-notes.md └── scripts └── check.sh /.gitignore: -------------------------------------------------------------------------------- 1 | # Binaries for programs and plugins 2 | *.exe 3 | *.dll 4 | *.so 5 | *.dylib 6 | 7 | # Test binary, build with `go test -c` 8 | *.test 9 | 10 | # Output of the go coverage tool 11 | *.out 12 | *.cov 13 | 14 | # Project-local glide cache, RE: https://github.com/Masterminds/glide/issues/736 15 | .glide/ 16 | 17 | /vendor 18 | /vendor.orig 19 | 20 | # debug executable 21 | debug 22 | 23 | # IDE specific 24 | .vscode/ 25 | /.idea 26 | 27 | local_dev 28 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | # Automated static checks 2 | 3 | language: bash 4 | 5 | services: 6 | 7 | before_install: 8 | 9 | script: 10 | scripts/check.sh 11 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /NOTICE: -------------------------------------------------------------------------------- 1 | This project is licensed to you under the Apache License, Version 2.0 (the "License"). 2 | 3 | You may not use this project except in compliance with the License. 4 | 5 | This project may include a number of subcomponents with separate copyright notices 6 | and license terms. Your use of these subcomponents is subject to the terms and 7 | conditions of the subcomponent's license, as noted in the LICENSE file. 8 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Service Manager Specification 2 | 3 | 4 | [![Build Status](https://travis-ci.org/Peripli/specification.svg?branch=master)](https://travis-ci.org/Peripli/specification) 5 | 6 | 7 | ## Table of Contents 8 | 9 | - [Notations and Terminology](#notations-and-terminology) 10 | - [Notational Conventions](#notational-conventions) 11 | - [Terminology](#terminology) 12 | - [Motivation](#motivation) 13 | - [How it works](#how-it-works) 14 | - [Concept details](#concept-details) 15 | - [API](#api) 16 | 17 | ## Notations and Terminology 18 | 19 | ### Notational Conventions 20 | 21 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 22 | "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to 23 | be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). 24 | 25 | ### Terminology 26 | 27 | This specification uses the terminology of the [Open Service Broker (OSB) API](https://github.com/openservicebrokerapi/servicebroker/). 28 | 29 | Additionally, this specification defines the following terms: 30 | 31 | - *Platform Type*: A concrete implementation of a platform. Examples are Cloud Foundry and Kubernetes. 32 | 33 | - *Platform Instance*: A deployment of a platform. For example, a Kubernetes cluster. 34 | 35 | - *Cloud Landscape*: A collection of Platform Instances of the same or different types. 36 | In many cases, a Cloud Landscape is operated by one cloud provider, 37 | but the services may be also consumable by platforms outside the landscape. 38 | 39 | - *Service Manager*: A component that acts as a platform as per OSB API and exposes a platform API. 40 | It allows the management and registration of service brokers and platform instances. 41 | Also acts as a central service broker. 42 | 43 | - *Service Broker Proxy*: A component that is associated with a platform that is registered at the Service Manager 44 | and is a service broker as per the OSB API specification. 45 | The proxy replicates the changes in the Service Manager into the platform instance in which the proxy resides. 46 | Service Brokers Proxies are in charge of registering and deregistering themselves at the platform it is responsible for. 47 | 48 | ## Motivation 49 | 50 | With Cloud Landscapes becoming bigger and more diverse, managing services is getting more difficult and new challenges arise: 51 | 52 | * Cloud providers are facing an increasing number of Platform Types, Platform Instances, supported IaaS and regions. 53 | At the same time, the number of services is increasing. 54 | Registering and managing a big amount of service brokers at a huge number of Platform Instances is infeasible. 55 | A central, Platform Instance independent component is needed to allow a sane management of service brokers. 56 | * So far, service instances are only accessible in the silo (platform) where they have been created. 57 | But there are use-cases that require sharing of a service instance across platforms. 58 | For example, a database created in Kubernetes should be accessible in Cloud Foundry. 59 | 60 | A standardized way is needed for managing broker registrations and propagating them 61 | to the registered Platform Instances when necessary. Also there should be a mechanism for tracking service instances creation 62 | that allows sharing of service instances across Platform Instances. 63 | 64 | ## How it works 65 | 66 | The Service Manager consists of multiple parts. 67 | The main part is the core component. 68 | It is the central registry for service broker and platform registration, as well as for tracking of all service instances. 69 | This core component communicates with the registered brokers and acts as a platform per Open Service Broker specification for them. 70 | 71 | In each Platform Instance resides a component called the Service Broker Proxy. 72 | It is the substitute for all brokers registered at the Service Manager 73 | in order to replicate broker registration and access visibility changes in the corresponding Platform Instance. It also delegates lifecycle operations to create/delete/bind/unbind service instances from the corresponding Platform Instance to the Service Manager and the services registered there. 74 | 75 | When a broker is registered or deregistered at the Service Manager, 76 | the Service Broker Proxy registers or deregisters itself in the name of this service broker. 77 | From a Platform Instance point of view, the broker proxy is indistinguishable from the real broker because both implement the OSB API. 78 | 79 | When the Platform Instance makes a call to the service broker, for example to provision a service instance, 80 | the broker proxy accepts the call, forwards it to the Service Manager, which in turn forwards it to the real broker. 81 | The response follows the same path back to the Platform Instance. 82 | Because all OSB calls go through the Service Manager, it can track all service instances and share them between Platform Instances. 83 | 84 | ## Concept Details 85 | Concept page to be added here. 86 | 87 | ## API 88 | 89 | [API Specification](./api.md) 90 | -------------------------------------------------------------------------------- /api.md: -------------------------------------------------------------------------------- 1 | # Service Manager API 2 | 3 | ## Table of Contents 4 | 5 | - [Overview](#overview) 6 | - [Terminology and Definitions](#terminology-and-definitions) 7 | - [Data Formats](#data-formats) 8 | - [Asynchronous Operations](#asynchronous-operations) 9 | - [General Resource Management](#general-resource-management) 10 | - [Creating a Resource Entity](#creating-a-resource-entity) 11 | - [Fetching a Resource Entity](#fetching-a-resource-entity) 12 | - [Listing All Resource Entities of a Resource Type](#listing-all-resource-entities-of-a-resource-type) 13 | - [Patching a Resource Entity](#patching-a-resource-entity) 14 | - [Deleting a Resource Entity](#deleting-a-resource-entity) 15 | - [Getting a specific operation for a resource](#getting-a-specific-operation-for-a-resource) 16 | - [Resource Types](#resource-types) 17 | - [Entity Relationships](#entity-relationships) 18 | - [Platform Management](#platform-management) 19 | - [Registering a Platform](#registering-a-platform) 20 | - [Fetching a Platform](#fetching-a-platform) 21 | - [Listing Platforms](#listing-platforms) 22 | - [Patching a Platform](#patching-a-platform) 23 | - [Deleting a Platform](#deleting-a-platform) 24 | - [Service Broker Management](#service-broker-management) 25 | - [Registering a Service Broker](#registering-a-service-broker) 26 | - [Fetching a Service Broker](#fetching-a-service-broker) 27 | - [Listing Service Brokers](#listing-service-brokers) 28 | - [Patching a Service Broker](#patching-a-service-broker) 29 | - [Deleting a Service Broker](#deleting-a-service-broker) 30 | - [Service Instance Management](#service-instance-management) 31 | - [Provisioning a Service Instance](#provisioning-a-service-instance) 32 | - [Fetching a Service Instance](#fetching-a-service-instance) 33 | - [Fetching a Service Instance Parameters](#fetching-a-service-instance-parameters) 34 | - [Listing Service Instances](#listing-service-instances) 35 | - [Patching a Service Instance](#patching-a-service-instance) 36 | - [Deleting a Service Instance](#deleting-a-service-instance) 37 | - [Service Binding Management](#service-binding-management) 38 | - [Creating a Service Binding](#creating-a-service-binding) 39 | - [Fetching a Service Binding](#fetching-a-service-binding) 40 | - [Fetching a Service Binding Parameters](#fetching-a-service-binding-parameters) 41 | - [Listing Service Bindings](#listing-service-bindings) 42 | - [Patching a Service Binding](#patching-a-service-binding) 43 | - [Deleting a Service Binding](#deleting-a-service-binding) 44 | - [Service Offering Management](#service-offering-management) 45 | - [Fetching a Service Offering](#fetching-a-service-offering) 46 | - [Listing Service Offerings](#listing-service-offerings) 47 | - [Patching a Service Offering](#patching-a-service-offering) 48 | - [Service Plan Management](#service-plan-management) 49 | - [Fetching a Service Plan](#fetching-a-service-plan) 50 | - [Listing Service Plans](#listing-service-plans) 51 | - [Patching a Service Plan](#patching-a-service-plan) 52 | - [Service Visibility Management](#service-visibility-management) 53 | - [Creating a Visibility](#creating-a-visibility) 54 | - [Fetching a Visibility](#fetching-a-visibility) 55 | - [Listing All Visibilities](#listing-all-visibilities) 56 | - [Patching a Visibility](#patching-a-visibility) 57 | - [Deleting a Visibility](#deleting-a-visibility) 58 | - [Operation Management](#operation-management) 59 | - [Information Management](#information-management) 60 | - [OSB Management](#osb-management) 61 | - [Credentials Object](#credentials-object) 62 | - [Operation Object](#operation-object) 63 | - [Labels Object](#labels-object) 64 | - [Errors](#errors) 65 | - [Mitigating Orphans](#mitigating-orphans) 66 | 67 | ## Overview 68 | 69 | The Service Manager API defines a REST interface that allows the management of Platforms, Service Brokers, Service Offerings, Service Plans, Service Instances and Service Bindings from a central place. The Service Manager API can be split into three groups: 70 | - A Service Manager Admin API to manage Service Brokers and attached Platforms. 71 | - A Service Controller API that allows the Service Manager to act as an OSB Platform for Service Brokers that are registered in Service Manager ("Service Manager as a Platform"). 72 | - An OSB API which allows the Service Manager to act as a Service Broker for Platforms that are registered in Service Manager ("Service Manager as a Broker"). The latter implements the [Open Service Broker (OSB) API](https://github.com/openservicebrokerapi/servicebroker/). 73 | 74 | One of the access channels to the Service Manager is via the [smctl CLI](https://github.com/Peripli/service-manager-cli). The API should play nice in this context. 75 | 76 | 77 | ## Terminology and Definitions 78 | 79 | This document inherits the terminology from the Service Manager specification and [Open Service Broker API](https://github.com/openservicebrokerapi/servicebroker/) specification. 80 | 81 | Additionally, the following terms and concepts are used: 82 | 83 | * *ID*: An ID is globally unique identifier. An ID MUST NOT be longer than 50 characters and SHOULD only contain characters from the "Unreserved Characters" as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.3). In other words: uppercase and lowercase letters, decimal digits, hyphen, period, underscore and tilde. Using a GUID is RECOMMENDED. 84 | * *CLI-friendly name*: A CLI-friendly name is a short string that SHOULD only use lowercase alphanumeric characters, periods and hyphens. Whitespaces are not allowed. A name MUST NOT exceed 255 character, but it is RECOMMENDED to keep it much shorter -- imagine a user having to type it as an argument for a longer command. 85 | * *Description*: A description is a human readable string, which SHOULD NOT exceed 255 characters. If a description is longer than 255 characters, the Service Manager MAY silently truncate it. 86 | 87 | ## Data Formats 88 | 89 | The data format for all Service Manager endpoints is [JSON](https://json.org). That implies that all strings are Unicode strings. 90 | 91 | The Service Manager deals with date-time values in some places. Because JSON lacks a date-time data type, date-time values are encoded as strings, following ISO 8601. The only supported date-time format is: `yyyy-mm-ddThh:mm:ss.s[Z|(+|-)hh:mm]` 92 | 93 | ### Content Type 94 | 95 | All requests and responses defined in this specification with accompanying bodies SHOULD contain a `Content-Type` HTTP header set to `application/json`. If the `Content-Type` is not set, Service Brokers and Platforms MAY still attempt to process the body. If a Service Broker rejects a request due to a mismatched `Content-Type` or the body is unprocessable it SHOULD respond with `400 Bad Request`. 96 | 97 | ## Authentication and Authorization 98 | 99 | Unless there is some out of band communication and agreement between a Service Manager client and the Service Manager, a client MUST authenticate with the Service Manager using OAuth 2.0 (the `Authorization:` header) on every request. 100 | 101 | The Service Manager MUST return a `401 Unauthorized` response if the authentication fails. 102 | 103 | The Service Manager MUST return a `403 Forbidden` response if the client is not authorized to perform the requested operation. 104 | 105 | In both cases, the response body SHOULD follow the [Errors](#errors) section. 106 | 107 | This specification does not define any permission model. Authorization checks are Service Manager implementation specific. However, the Service Manager SHOULD follow these basic guidelines: 108 | 109 | * If a user is allowed to update or delete an entity, the user SHOULD also be allowed to fetch and list the entity and to see the operations for the entity. 110 | * If a user is allowed to see an entity, the user SHOULD have access to *all* fields and labels of the entity. 111 | * The Service Manager MAY restrict write access to some fields and labels. There is no way for the client to find out in advance which data can be set and updated. 112 | 113 | ## Asynchronous Operations 114 | 115 | The Service Manager APIs for creating, updating, and deleting entities MAY work asynchronously. When such an operation is triggered, the Service Manager MAY respond with `202 Accepted` and a `Location header` specifying a URL to obtain the [operation](#operation-object). A Service Manager client MAY then use the Location header's value to [poll for the operation status](#getting-a-specific-operation-for-a-resource). Once the operation has finished (successfully or not), the client SHOULD stop polling. The Service Manager keeps and provides [operation status](#operation-object) for certain period of time after the operation has finished. 116 | The Service Manager MAY decide to execute operations synchronously. In this case it responses with `200 Ok`, `201 Created`, or `204 No Content`, depending on the operation. 117 | 118 | ### Concurrent Mutating Requests 119 | 120 | Service Manager MAY NOT support concurrent mutating operations on the same resource entity. If a resource with type `:resource_type` and ID `:resource_id` is currently being created, updated, patched, or deleted and this operation is in progress, then other mutating operation MAY fail on the resource of type `:resource_type` and ID `:resource_id` until the one that is currently in progress finishes. If the Service Manager receives a concurrent mutating request that it currently cannot handle due to another operation being in progress for the same resource entity, the Service Manager MUST reject the request and return HTTP status `422 Unprocessable Entity` and a meaningful [error](#errors). 121 | The client MAY retry the request after the currently running operation has finished. 122 | 123 | ## General Resource Management 124 | 125 | The following section generalizes how Service Manager resources are managed. A `resource_type` represents one set of resource entities (for example service brokers). A `resource_entity` represents one record of a resource type (for example one service broker record). 126 | 127 | ### Creating a Resource Entity 128 | 129 | #### Request 130 | 131 | ##### Route 132 | 133 | `POST /v1/:resource_type` 134 | 135 | `:resource_type` MUST be a valid Service Manager [resource type](#resource-types). 136 | 137 | ##### Body 138 | 139 | The body MUST be a valid JSON Object. 140 | 141 | Some APIs MAY allow passing in the resource entity `id` (that is the ID to be used to uniquely identify the resource entity) for backward compatibility reasons. If an `id` is not passed as part of the request body, the Service Manager takes care of generating one. 142 | 143 | #### Response 144 | 145 | | Status Code | Description | 146 | | ----------- | ----------- | 147 | | 201 Created | MUST be returned if the resource has been created. | 148 | | 202 Accepted | MUST be returned if a resource creation is successfully initiated as a result of this request. | 149 | | 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | 150 | | 409 Conflict | MUST be returned if a resource with the same `name` or `id` already exists. | 151 | | 422 Unprocessable Entity | MUST be returned if another create/update/patch operation for a resource with the same `name` or `id` is already in progress. | 152 | 153 | Responses with a status code >= 400 will be interpreted as a failure. The response SHOULD include a user-facing message in the `description` field. For details see [Errors](#errors). 154 | 155 | ##### Headers 156 | 157 | | Header | Type | Description | 158 | | ------ | ---- | ----------- | 159 | | Location | string | An URL from where the result for the [operation](#operation-object) can be obtained. This header MUST be present if the status `202 Accepted` has been returned and MUST NOT be present for all other status codes. | 160 | 161 | ##### Body 162 | 163 | Unless defined otherwise in the sections below, the response body MUST be [the representation of the entity](#fetching-a-resource-entity) if the status code is `201 Created` or empty JSON `{}` if the status code is `202 Accepted`. 164 | 165 | ### Fetching a Resource Entity 166 | 167 | #### Request 168 | 169 | ##### Route 170 | 171 | `GET /v1/:resource_type/:resource_entity_id` 172 | 173 | `:resource_type` MUST be a valid Service Manager [resource type](#resource-types). 174 | 175 | `:resource_entity_id` MUST be the ID of a previously created resource entity of this resource type. 176 | 177 | #### Response 178 | 179 | | Status Code | Description | 180 | | ----------- | ----------- | 181 | | 200 OK | MUST be returned if the request execution has been successful. The expected response body is below. | 182 | | 404 Not Found | MUST be returned if the requested resource is missing, if the creation operation is still in progress, or if the user is not allowed to know this resource. | 183 | 184 | Responses with a status code >= 400 will be interpreted as a failure. The response SHOULD include a user-facing message in the `description` field. For details see [Errors](#errors). 185 | 186 | ##### Body 187 | 188 | The response body MUST be a valid JSON Object. Each resource API in this document should include a relevant example. 189 | 190 | In case of an ongoing asynchronous update or patch of the resource entity, this operation MUST return the old fields' values (the one known prior to the update as there is no guarantee if the update will be successful). 191 | 192 | ### Listing All Resource Entities of a Resource Type 193 | 194 | Returns all or a subset of the resource entities of this resource type. 195 | 196 | #### Request 197 | 198 | ##### Route 199 | 200 | `GET /v1/:resource_type` 201 | 202 | `:resource_type` MUST be a valid Service Manager [resource type](#resource-types). 203 | 204 | #### Filtering Parameters 205 | 206 | There are two types of filtering. 207 | 208 | 1. Filtering based on top-level resource fields. 209 | 2. Filtering based on labels. 210 | 211 | Filtering can be controlled by the following query parameters: 212 | 213 | | Query-String Field | Type | Description | 214 | | ------------------ | ---- | ----------- | 215 | | fieldQuery | string | Filters the response based on the field query. Only items that have field values matching the provided field query will be returned. If present, MUST be a non-empty string. | 216 | | labelQuery | string | Filters the response based on the label query. Only items that have label values matching the provided label query will be returned. If present, MUST be a non-empty string. | 217 | 218 | Field query example: `GET /v1/service_instances?fieldQuery=service_plan_id+eq+'bvsded31-c303-123a-aab9-8crar19e1218'` would return all service instances with a service plan ID that equals `bvsded31-c303-123a-aab9-8crar19e1218`. 219 | 220 | Label query example: `GET /v1/service_instances?labelQuery=context_id+eq+'ad8cddb0-4679-43bf-89bc-357e9a638f30'` would return all service instances with a label `context_id` that has a value `ad8cddb0-4679-43bf-89bc-357e9a638f30`. 221 | 222 | ##### Filter Syntax and Rules 223 | 224 | The Service Manager SHOULD support field queries on top-level fields with string and boolean values and MAY support fields with integer and date-time values. The interpretation of other value types or object is implementation specific. In general, the Service Manager SHOULD reject field queries for all other value types. 225 | 226 | A BNF-like definition of a query looks like this: 227 | ``` 228 | query := predicate | predicate "and" predicate 229 | predicate := comparison_predicate | in_predicate | exists_predicate 230 | 231 | comparison_predicate := (field | label) comp_op literal 232 | comp_op := "eq" | "en" | "ne" | "gt" | "lt" | "ge" | "le" 233 | 234 | in_predicate := (field | label) ("in" | "notin") "(" literals ")" 235 | 236 | field := !! field name or field path 237 | label := !! label name 238 | 239 | literals := literal ["," literals] 240 | literal := string_literal | boolean_literal | integer_literal | datetime_literal 241 | ``` 242 | 243 | * `string_literal`: String values MUST be enclosed in single quotes ('`'`'). Single quotes in strings MUST be encoded with another single quote ('`''`'). 244 | * `boolean_literal`: Boolean values MUST be either '`true`' or '`false`' and MUST NOT be enclosed in quotes. 245 | * `integer_literal`: Integer values MUST be only consist of digits with one optional leading '`+`' or '`-`' sign. 246 | * `datetime_literal`: Date-time values MUST follow ISO 8601 and MUST NOT be enclosed in quotes. See also the [Data Formats](#data-formats) section. 247 | 248 | The Service Manager MUST support the following operators: 249 | 250 | | Operator | Field Query | Label Query | 251 | | -------- | ----------- | ----------- | 252 | | eq | Evaluates to true if the field value matches the literal. False otherwise. | Evaluates to true if the label exists and one label value matches the literal. False otherwise. | 253 | | en | Evaluates to true if the field value matches the literal or if the field value is `null`. False otherwise. | Evaluates to true if the label exists and one label value matches the literal or if the label doesn't exist. False otherwise. | 254 | | ne | Evaluates to true if the field value does not matches the literal. False otherwise. | Evaluates to true if the label exists and no label value matches the literal. False otherwise. | 255 | | in | Evaluates to true if the field value matches at least one value in the list of literals. False otherwise. | Evaluates to true if the label exists and at least a label value matches one value in the list of literals. False otherwise. | 256 | | notin | Evaluates to true if the field value does not match any value in the list of literals. False otherwise. | Evaluates to true if the label exists and no label value matches any value in the list of literals. False otherwise. | 257 | | and | Evaluates to true if both the left and right operands evaluate to true. False otherwise. | Evaluates to true if both the left and right operands evaluate to true. False otherwise. | 258 | 259 | Additionally, the Service Manager MAY support one or multiple of the following operators for field queries: 260 | 261 | | Operator | Field Query | 262 | | -------- | ----------- | 263 | | gt | Evaluates to true if the field value is greater than the literal. False otherwise. | 264 | | ge | Evaluates to true if the field value is greater or equal than the literal. False otherwise. | 265 | | lt | Evaluates to true if the field value is less than the literal. False otherwise. | 266 | | le | Evaluates to true if the field value is less or equal than the literal. False otherwise. | 267 | 268 | Label and field queries MAY be combined. The returned list MUST only contain entries that match both queries. 269 | 270 | ##### Query examples: 271 | 272 | * List all bindings of the plan "small" or "medium" of service "mysql" provided by the broker with the ID "f85bcbd3-6c8b-43f0-a019-7f0a1ec5dba4": 273 | Field query: `broker_id eq 'f85bcbd3-6c8b-43f0-a019-7f0a1ec5dba4' and service_name eq 'mysql' and plan_name in ('small', 'medium')` 274 | 275 | * List all instances of service "postgresql" that are managed by the Service Manager and that are not orphans: 276 | Field query: `platform_id eq 'service-manager' and service_name eq 'postgresql' and orphan ne true` 277 | 278 | * List all Platforms of type "kubernetes" that are labeled as "dev" Platform (assuming there is a label called "purpose"): 279 | Field query: `type eq 'kubernetes'` 280 | Label query: `purpose eq 'dev'` 281 | 282 | #### Paging Parameters 283 | 284 | All `List` endpoints MUST return the list of entities ordered by creation date and entity ID. 285 | Clients define the beginning of the result set by setting the `token` parameter. If this parameter is missing or empty, the first page is returned. To retrieves subsequent pages, the client has to provide the token value that was included in the previous page. 286 | The Service Manager MUST provide an [appropriate error](#errors) if the provided token is invalid. In this case, the client has to reiterate the list from the beginning. 287 | Clients control the size of the result set by setting the `max_items` parameter. 288 | 289 | Paging can be controlled by the following query string parameters: 290 | 291 | | Query-String Field | Type | Description | 292 | | ------------------ | ---- | ----------- | 293 | | token | string | the token that was included in the previous page. The first page is requested by either not providing this parameter or providing an empty string. | 294 | | max_items | int | the maximum number of items to return in the response. The server MUST NOT exceed this maximum but MAY return a smaller number of items than the specified value. The server SHOULD NOT return an error if `max_items` exceeds the internally supported page size. It SHOULD return a smaller number of items instead. If the client sets `max_items` to 0, it is assumed that the client is only interested in the total number of items. The default is implementation specific. | 295 | 296 | ##### Paging Response Headers 297 | 298 | | Header | Type | Description | 299 | | ------ | ---- | ----------- | 300 | | Link | string | If the response contains a `token` field, a `Link` header of type `rel="next"` SHOULD be returned (see [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288.html#section-3.3)). If there is no `token` field, this header MUST NOT be present. | 301 | 302 | 303 | #### Response 304 | 305 | | Status Code | Description | 306 | | ----------- | ----------- | 307 | | 200 OK | MUST be returned upon successful retrieval of the resource entities. The expected response body is below. | 308 | | 400 Bad Request | MUST be returned if the value of the `max_items` parameter is a negative number. | 309 | | 404 NotFound | MUST be returned if the `token` parameter references an unknown for the current user entity. | 310 | 311 | Responses with a status code >= 400 will be interpreted as a failure. The response SHOULD include a user-facing message in the `description` field. For details see [Errors](#errors). 312 | 313 | 314 | ##### Body 315 | 316 | The response body MUST be a valid JSON Object. 317 | 318 | | Response Field | Type | Description | 319 | | -------------- | ---- | ----------- | 320 | | token | string | an opaque token that is required for fetching the next page. If the list contains additional items after those contained in the response, this MUST be a non-empty string. Otherwise this field MUST NOT be present. If this field is present, a request with a larger `max_items` value is expected to return additional results (unless the list has changed or `max_items` exceeds the internally supported page size). | 321 | | num_items | int | if the server knows the total number of items in the result set, the server SHOULD include the number here. If the server does not know the number of items in the result set, this field MUST NOT be included. The value MAY NOT be accurate the next time the client retrieves the result set or the next page in the result set. | 322 | | items* | array of objects | the list of items. This list MAY be empty. | 323 | 324 | \* Fields with an asterisk are REQUIRED. 325 | 326 | ```json 327 | { 328 | "token": "token1234", 329 | "num_items": 42, 330 | "items": [ 331 | { 332 | "id": "a62b83e8-1604-427d-b079-200ae9247b60", 333 | ... 334 | }, 335 | ... 336 | ] 337 | } 338 | ``` 339 | 340 | ### Patching a Resource Entity 341 | 342 | #### Request 343 | 344 | ##### Route 345 | 346 | `PATCH /v1/:resource_type/:resource_entity_id` 347 | 348 | `:resource_type` MUST be a valid Service Manager [resource type](#resource-types). 349 | 350 | `:resource_entity_id` MUST be the ID of a previously created resource entity of this resource type. 351 | 352 | ##### Body 353 | 354 | The body MUST be a valid JSON object. Each resource API in this document should include a relevant example. 355 | 356 | The body MUST provide the same data and structure that is used for creating an entity of this resource type (except for the `label` object), but all fields are OPTIONAL. Fields that are not provided, MUST NOT be changed. Fields that are explicitly supplied a `null` value MUST be nulled out provided that they are not mandatory for the resource type. 357 | 358 | Patching the resource labels is specified in the [Patching Labels section](#patching-labels). 359 | 360 | #### Response 361 | 362 | | Status Code | Description | 363 | | ----------- | ----------- | 364 | | 200 OK | MUST be returned if the resource has been updated. | 365 | | 202 Accepted | MUST be returned if a resource updating is successfully initiated as a result of this request. | 366 | | 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data or attempting to null out mandatory fields. | 367 | | 404 Not Found | MUST be returned if the requested resource is missing or if the user is not allowed to know this resource. | 368 | | 409 Conflict | MUST be returned if a resource with a different `id` but the same `name` is already registered with the Service Manager and Service Manager enforces uniqueness on the `name` in the registration context. | 369 | | 422 Unprocessable Entity | MUST be returned if another create/update/patch operation in already in progress. | 370 | 371 | Responses with a status code >= 400 will be interpreted as a failure. The response SHOULD include a user-facing message in the `description` field. For details see [Errors](#errors). 372 | 373 | ##### Headers 374 | 375 | | Header | Type | Description | 376 | | ------ | ---- | ----------- | 377 | | Location | string | An URL from where the result for the [operation](#operation-object) can be obtained. This header MUST be present if the status `202 Accepted` has been returned and MUST NOT be present for all other status codes. | 378 | 379 | ##### Body 380 | 381 | | Status Code | Description | 382 | | ----------- | ----------- | 383 | | 200 OK | Representation of the updated entity. The returned JSON object MUST be the same that is returned by the corresponding [fetch endpoint](#fetching-a-resource-entity). | 384 | | 202 Accepted | Empty json `{}`. | 385 | | 4xx | An [Error Object](#errors). | 386 | 387 | ### Deleting a Resource Entity 388 | 389 | #### Request 390 | 391 | ##### Route 392 | 393 | `DELETE /v1/:resource_type/:resource_entity_id` 394 | 395 | `:resource_type` MUST be a valid Service Manager [resource type](#resource-types). 396 | 397 | `:resource_entity_id` MUST be the ID of a previously created resource entity of this resource type. 398 | 399 | #### Response 400 | 401 | | Status Code | Description | 402 | | ----------- | ----------- | 403 | | 200 OK | MUST be returned if the resource has been deleted. The body MUST be a non-empty, valid JSON object. If no data should be be returned from the Service Manager, the status code `204 No Content` SHOULD be used. | 404 | | 202 Accepted | MUST be returned if a resource deletion is successfully initiated as a result of this request. | 405 | | 204 No Content | MUST be returned if the resource has been deleted and there is no additional data provided by the Service Manager. | 406 | | 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | 407 | | 404 Not Found | MUST be returned if the requested resource is missing or if the user is not allowed to know this resource. | 408 | | 409 Conflict | MUST be returned if associated entities exist | 409 | | 422 Unprocessable Entity | MUST be returned if another operation in already in progress. | 410 | 411 | Responses with a status code >= 400 will be interpreted as a failure. The response SHOULD include a user-facing message in the `description` field. For details see [Errors](#errors). 412 | 413 | ##### Headers 414 | 415 | | Header | Type | Description | 416 | | ------ | ---- | ----------- | 417 | | Location | string | An URL from where the result for the [operation](#operation-object) can be obtained. This header MUST be present if the status `202 Accepted` has been returned and MUST NOT be present for all other status codes. | 418 | 419 | ##### Body 420 | 421 | | Status Code | Description | 422 | | ----------- | ----------- | 423 | | 200 OK | A valid JSON object. | 424 | | 202 Accepted | Empty json `{}`. | 425 | | 204 No Content | No body MUST be provided. | 426 | | 4xx | An [Error Object](#errors). | 427 | 428 | ### Getting a specific operation for a resource 429 | 430 | #### Request 431 | 432 | ##### Route 433 | 434 | `GET /v1/:resource_type/:resource_id/operations/:operation_id` 435 | 436 | `:resource_id` MUST be the ID of a previously created resource entity of this resource type. 437 | 438 | `:resource_type` MUST be a valid Service Manager [resource type](#resource-types). 439 | 440 | `:operation_id` is an opaque operation identifier. 441 | 442 | #### Response 443 | 444 | | Status Code | Description | 445 | | ----------- | ----------- | 446 | | 200 OK | MUST be returned if the request execution has been successful. The expected response body is below. | 447 | | 404 Not Found | MUST be returned if the requested resource is missing or if the user is not allowed to know this resource. | 448 | 449 | Responses with a status code >= 400 will be interpreted as a failure. The response SHOULD include a user-facing message in the `description` field. For details see [Errors](#errors). 450 | 451 | ##### Body 452 | 453 | ```json 454 | { 455 | "id": "42fcdf1f-79bc-43e1-8865-844e82d0979d", 456 | "description": "Working on it.", 457 | "correlation_id": "12fcdf1f-79bc-43e1-8865-844e82d0979d", 458 | "state": "in progress", 459 | "type": "create", 460 | "external_id": "a12fcdf1f-79bc-43e1-8865-844e82d0979", 461 | "created_at": "2019-07-09T17:50:00.01Z", 462 | "updated_at": "2019-07-09T17:50:00.01Z", 463 | "resource_id": "c67ebb30-a71a-4c23-81c6-f79fae6fe457", 464 | "resource_type": "/v1/service_instances", 465 | "reschedule": false, 466 | "reschedule_timestamp": "2019-07-09T19:50:00.01Z", 467 | "platform_id": "service-manager", 468 | "deletion_scheduled": "2019-07-09T19:50:00.01Z", 469 | "ready": true, 470 | "transitive_resources": {} 471 | } 472 | ``` 473 | 474 | ## Resource Types 475 | 476 | Service Manager currently defines the following resource types the APIs for which MUST comply with the [general resource management section](#general-resource-management). 477 | 478 | ### Platforms 479 | 480 | The `platforms` API is described [here](#platform-management). 481 | 482 | Definition of the semantics behind the resource can be found in the [OSB specification](https://github.com/openservicebrokerapi/servicebroker/blob/v2.14/spec.md#terminology). 483 | 484 | ### Service Brokers 485 | 486 | The `service brokers` API is described [here](#service-broker-management). 487 | 488 | Definition of the semantics behind the resource name can be found in the [OSB specification](https://github.com/openservicebrokerapi/servicebroker/blob/v2.14/spec.md#terminology). 489 | 490 | ### Service Instances 491 | 492 | The `service instances` API is described [here](#service-instance-management). 493 | 494 | Definition of the semantics behind the resource name can be found in the [OSB specification](https://github.com/openservicebrokerapi/servicebroker/blob/v2.14/spec.md#terminology). 495 | 496 | ### Service Bindings 497 | 498 | The `service bindings` API is described [here](#service-binding-management). 499 | 500 | Definition of the semantics behind the resource name can be found in the [OSB specification](https://github.com/openservicebrokerapi/servicebroker/blob/v2.14/spec.md#terminology). 501 | 502 | ### Service Offerings 503 | 504 | The `service offerings` API is described [here](#service-offering-management). 505 | 506 | Definition of the semantics behind the resource name can be found in the [OSB specification](https://github.com/openservicebrokerapi/servicebroker/blob/v2.14/spec.md#terminology). 507 | 508 | A Service Offering has two unique keys. There is the internal service ID (`service_offering_id`) which is generated by the Service Manager when a broker is registered. If multiple brokers register the same service, each Service Offering gets a different internal service ID. And there is the pair of broker ID (`borker_id`) and service ID (`service_id`). This service ID is the ID provided in the catalog of a broker. Because multiple brokers can provide the same service and service ID, the broker ID is required to specify the Service Offering. 509 | 510 | ### Service Plans 511 | 512 | The `service plans` API is described [here](#service-plan-management). 513 | 514 | Definition of the semantics behind the resource name can be found in the [OSB specification](https://github.com/openservicebrokerapi/servicebroker/blob/v2.14/spec.md#terminology). 515 | 516 | ### Service Visibilities 517 | 518 | The `service visibilities` resource represents enforced visibility policies for Service Offerings and Plans. This allows the Service Manager to specify where Service Plans are visible (in which Platforms, CF orgs, etc). 519 | 520 | The `service visibilities` API is described [here](#service-visibility-management). 521 | 522 | ### Operations 523 | 524 | The `operations` resource represents REST operations that are executed via SM API. This allows the Service Manager to provide additional details about each REST operation. 525 | 526 | The `operations` API is described [here](#operation-management). 527 | 528 | ## Entity Relationships 529 | 530 | There are different types of relationships between the different entity types. This section describes these relationships. 531 | 532 | Broker Visibility ---> Platform Operations 533 | | | | ^ 534 | | +----------+ | | 535 | | | | | 536 | v v v | 537 | Offering ----> Plan <------- Instance <---- Binding 538 | 539 | 540 | ### Service Brokers, Service Offerings and Service Plans 541 | 542 | Service Offerings and Service Plans depend on the Service Broker that defines them. They come and go with the Service Broker. 543 | 544 | The removal of a Service Broker MUST fail if there is still a Service Instance of a Service Plan of that broker. 545 | 546 | ### Platforms 547 | 548 | Platforms do not depend on any other entity. 549 | 550 | The removal of a Platform MUST fail if there is still a Service Instance associated with that Platform. 551 | 552 | ### Service Instances and Service Bindings 553 | 554 | Service Instances depend on Service Plans (and with that on a Service Brokers) and on Platforms. 555 | Service Bindings depend on Service Instances and therefore also on Service Brokers and Platforms. 556 | 557 | The deprovisioning of a Service Instance MUST fail if there is at least one Service Binding of that instance. 558 | 559 | Service Instances and Service Bindings are "owned" by a Platform. Only the Platform that created the instance or binding is allowed to update and delete those. 560 | 561 | It is not possible to delete a Service Instance through the Service Manager API that has been created by an attached Platform. Only the attached Platform can delete such an instance through the OSB API. 562 | The delete operation of the Service Manager API only works for instances that have been created through the Service Manager API and where therefore the Service Manager is the owning Platform. 563 | 564 | ### Visibilities 565 | 566 | Visibilities depend on a Service Plan (and with that on a Service Broker) and a Platform. 567 | 568 | If either the Service Plan (the Service Broker) or the Platform goes away, all related Visibilities have to automatically vanish, too. 569 | 570 | ### Operations 571 | 572 | Operations can exist even after the resource they represent is deleted. This means that when the actual resource is deleted, the operation will stay. 573 | 574 | ## Platform Management 575 | 576 | ### Registering a Platform 577 | 578 | In order for a Platform to be usable with the Service Manager, the Service Manager needs to know about the Platform's existence. Essentially, registering a Platform would allow the Service Manager to manage the service brokers and service visibilities in this Platform. 579 | 580 | Creation of a `platform` resource entity MUST comply with [creating a resource entity](#creating-a-resource-entity). 581 | 582 | #### Route 583 | 584 | `POST /v1/platforms` 585 | 586 | #### Request Body 587 | 588 | ```json 589 | { 590 | "id": "038001bc-80bd-4d67-bf3a-956e4d545e3c", 591 | "name": "cf-eu-10", 592 | "type": "cloudfoundry", 593 | "description": "Cloud Foundry on AWS in Frankfurt.", 594 | "labels": { 595 | "label1": ["value1"] 596 | } 597 | } 598 | ``` 599 | 600 | | Request field | Type | Description | 601 | | ------------- | ---- | ----------- | 602 | | id | string | ID of the Platform. If provided, MUST be unique across all Platforms registered with the Service Manager. If not provided, the Service Manager generates an ID. | 603 | | name* | string | A CLI-friendly name of the Platform. MUST be unique across all Platforms registered with the Service Manager. MUST be a non-empty string. | 604 | | type* | string | The type of the Platform. MUST be a non-empty string. SHOULD be one of the values defined for `platform` field in OSB [context](https://github.com/openservicebrokerapi/servicebroker/blob/master/profile.md#context-object). | 605 | | description | string | A description of the Platform. | 606 | | labels | collection of [labels](#labels-object) | Additional data associated with the resource entity. MAY be an empty object. | 607 | 608 | \* Fields with an asterisk are REQUIRED 609 | 610 | ### Fetching a Platform 611 | 612 | Fetching of a `platform` resource entity MUST comply with [fetching a resource entity](#fetching-a-resource-entity). 613 | 614 | #### Route 615 | 616 | `GET /v1/platforms/:platform_id` 617 | 618 | `:platform_id` MUST be the ID of an existing Platform. 619 | 620 | #### Response Body 621 | 622 | ##### Platform Object 623 | 624 | ```json 625 | { 626 | "id": "038001bc-80bd-4d67-bf3a-956e4d545e3c", 627 | "name": "cf-eu-10", 628 | "type": "cloudfoundry", 629 | "description": "Cloud Foundry on AWS in Frankfurt.", 630 | "created_at": "2016-06-08T16:41:22.23Z", 631 | "updated_at": "2016-06-08T16:41:26.471Z", 632 | "labels": { 633 | "label1": ["value1"] 634 | }, 635 | "ready": true 636 | } 637 | ``` 638 | 639 | | Response field | Type | Description | 640 | | -------------- | ---- | ----------- | 641 | | id | string | ID of the Platform. | 642 | | name | string | Platform name. | 643 | | type | string | Type of the Platform. | 644 | | description | string | Platform description. | 645 | | created_at | string | The time of the creation [in ISO 8601 format](#data-formats). | 646 | | updated_at | string | The time of the last update [in ISO 8601 format](#data-formats). | 647 | | labels | collection of [labels](#labels-object) | Additional data associated with the resource entity. MAY be an empty object. | 648 | | ready | bool | whether the resource is ready or not. | 649 | 650 | ### Listing Platforms 651 | 652 | Listing `platforms` MUST comply with [listing all resource entities of a resource type](#listing-all-resource-entities-of-a-resource-type). 653 | 654 | #### Route 655 | 656 | `GET /v1/platforms` 657 | 658 | #### Response Body 659 | 660 | ```json 661 | { 662 | 663 | "num_items": 2, 664 | "items": [ 665 | { 666 | "id": "038001bc-80bd-4d67-bf3a-956e4d545e3c", 667 | "name": "cf-eu-10", 668 | "type": "cloudfoundry", 669 | "description": "Cloud Foundry on AWS in Frankfurt.", 670 | "created_at": "2016-06-08T16:41:22.25Z", 671 | "updated_at": "2016-06-08T16:41:26.6Z", 672 | "labels": { 673 | "label1": ["value1"] 674 | }, 675 | "ready": true 676 | }, 677 | { 678 | "id": "e031d646-62a5-4a50-9d8e-23165172e9e1", 679 | "name": "k8s-us-05", 680 | "type": "kubernetes", 681 | "description": "Kubernetes on GCP in us-west1.", 682 | "created_at": "2016-06-08T17:41:22.0Z", 683 | "updated_at": "2016-06-08T17:41:26.294Z", 684 | "labels": { 685 | }, 686 | "ready": true 687 | } 688 | ] 689 | } 690 | ``` 691 | 692 | ### Patching a Platform 693 | 694 | Patching of a `platform` resource entity MUST comply with [patching a resource entity](#patching-a-resource-entity). 695 | 696 | #### Route 697 | 698 | `PATCH /v1/platforms/:platform_id` 699 | 700 | `:platform_id` The ID of an existing Platform. 701 | 702 | ##### Parameters 703 | 704 | | Query-String Field | Type | Description | 705 | | ------------------ | ---- | ----------- | 706 | | regenerateCredentials | boolean | Indicates whether to regenerate credentials. The default is false. 707 | 708 | ##### Request Body 709 | 710 | See [Registering a Platform](#registering-a-platform) and [Patching Labels](#patching-labels). 711 | 712 | 713 | 714 | ### Deleting a Platform 715 | 716 | Deletion of a `platform` resource entity MUST comply with [deleting a resource entity](#deleting-a-resource-entity). 717 | 718 | All [Service Visibilities](#service-visibility-management) entries that belong to this `platform` resource entity are automatically removed. 719 | 720 | #### Route 721 | 722 | `DELETE /v1/platforms/:platform_id` 723 | 724 | `:platform_id` MUST be the ID of an existing Platform. 725 | 726 | ## Service Broker Management 727 | 728 | ### Registering a Service Broker 729 | 730 | Registering a broker in the Service Manager makes the services exposed by this service broker available to all Platforms registered in the Service Manager. 731 | Upon registration, Service Manager fetches and validates the catalog from the service broker. 732 | 733 | Creation of a `service broker` resource entity MUST comply with [creating a resource entity](#creating-a-resource-entity). 734 | 735 | #### Route 736 | 737 | `POST /v1/service_brokers` 738 | 739 | #### Request Body 740 | 741 | ```json 742 | { 743 | "name": "service-broker-name", 744 | "description": "Service broker providing some valuable services.", 745 | "broker_url": "http://service-broker.example.com", 746 | "credentials": { 747 | "basic": { 748 | "username": "admin", 749 | "password": "secret" 750 | } 751 | }, 752 | "labels": { 753 | "label1": ["value1"] 754 | } 755 | } 756 | ``` 757 | 758 | Alternatively, if the broker uses client certificate authentication, TLS credentials should be provided: 759 | 760 | ```json 761 | { 762 | "name": "service-broker-name", 763 | "description": "Service broker providing some valuable services.", 764 | "broker_url": "http://service-broker.example.com", 765 | "credentials": { 766 | "tls": { 767 | "client_certificate": "-----BEGIN CERTIFICATE-----CCAD8jCdAtqgAwIBAgINfc...-----END CERTIFICATE-----", 768 | "client_key": "-----BEGIN RSA PRIVATE KEY-----MIIEowIBAAKCAQ...-----END RSA PRIVATE KEY-----" 769 | } 770 | }, 771 | "labels": { 772 | "label1": ["value1"] 773 | } 774 | } 775 | ``` 776 | 777 | Atleast one of the `basic` or `tls` credentials options MUST be specified during broker registration. 778 | 779 | | Name | Type | Description | 780 | | ---- | ---- | ----------- | 781 | | name* | string | A CLI-friendly name of the service broker. The Service Manager MAY change this name to make it unique across all registered brokers. MUST be a non-empty string. | 782 | | description | string | A description of the service broker. | 783 | | broker_url* | string | MUST be a valid base URL for an application that implements the OSB API. | 784 | | credentials* | [credentials](#credentials-object) | MUST be a valid credentials object which will be used to authenticate against the service broker. | 785 | | labels | collections of [labels](#labels-object) | Additional data associated with the service broker. | 786 | 787 | \* Fields with an asterisk are REQUIRED. 788 | 789 | ### Fetching a Service Broker 790 | 791 | Fetching of a `service broker` resource entity MUST comply with [fetching a resource entity](#fetching-a-resource-entity). 792 | 793 | #### Request 794 | 795 | ##### Route 796 | 797 | `GET /v1/service_brokers/:broker_id` 798 | 799 | `:broker_id` MUST be the ID of an existing service broker. 800 | 801 | ##### Response Body 802 | 803 | ##### Service Broker Object 804 | 805 | ```json 806 | { 807 | "id": "36931aaf-62a7-4019-a708-0e9abf7e7a8f", 808 | "name": "service-broker-name", 809 | "description": "Service broker providing some valuable services.", 810 | "created_at": "2016-06-08T16:41:26.734Z.104", 811 | "updated_at": "2016-06-08T16:41:26.104Z", 812 | "broker_url": "https://service-broker-url", 813 | "labels": { 814 | "label1": ["value1"] 815 | }, 816 | "ready": true 817 | } 818 | ``` 819 | 820 | | Response Field | Type | Description | 821 | | -------------- | ---- | ----------- | 822 | | id | string | ID of the service broker. | 823 | | name | string | Name of the service broker. | 824 | | description | string | Description of the service broker. | 825 | | broker_url | string | URL of the service broker. | 826 | | created_at | string | The time of creation [in ISO 8601 format](#data-formats). | 827 | | updated_at | string | The time of the last update [in ISO 8601 format](#data-formats). | 828 | | labels | collection of [labels](#labels-object) | Additional data associated with the service broker. MAY be an empty object. | 829 | | ready | bool | whether the resource is ready or not. | 830 | 831 | ### Listing Service Brokers 832 | 833 | Listing `service brokers` MUST comply with [listing all resource entities of a resource type](#listing-all-resource-entities-of-a-resource-type). 834 | 835 | #### Route 836 | 837 | `GET /v1/service_brokers` 838 | 839 | #### Response Body 840 | 841 | ```json 842 | { 843 | "num_item": 2, 844 | "items": [ 845 | { 846 | "id": "36931aaf-62a7-4019-a708-0e9abf7e7a8f", 847 | "name": "service-broker-name", 848 | "description": "Service broker providing some valuable services.", 849 | "created_at": "2016-06-08T16:41:26.104Z", 850 | "updated_at": "2016-06-08T16:41:26.104", 851 | "broker_url": "https://service-broker-url", 852 | "labels": { 853 | "label1": ["value1"] 854 | }, 855 | "ready": true 856 | }, 857 | { 858 | "id": "a62b83e8-1604-427d-b079-200ae9247b60", 859 | "name": "another-broker", 860 | "description": "More services.", 861 | "created_at": "2016-06-08T17:41:26.104Z", 862 | "updated_at": "2016-06-08T17:41:26.104Z", 863 | "broker_url": "https://another-broker-url", 864 | "labels": { 865 | }, 866 | "ready": true 867 | } 868 | ] 869 | } 870 | ``` 871 | 872 | ### Patching a Service Broker 873 | 874 | Updating of a `service broker` resource entity MUST comply with [patching a resource entity](#patching-a-resource-entity). 875 | 876 | Patching a service broker (even with an empty JSON object `{}`) MUST trigger an update of the catalog of this service broker. 877 | 878 | #### Route 879 | 880 | `PATCH /v1/service_brokers/:broker_id` 881 | 882 | `:broker_id` MUST be the ID of an existing service broker. 883 | 884 | #### Request Body 885 | 886 | See [Registering a Service Broker](#registering-a-service-broker) and [Patching Labels](#patching-labels). 887 | 888 | ### Deleting a Service Broker 889 | 890 | Deletion of a `service broker` resource entity MUST comply with [deleting a resource entity](#deleting-a-resource-entity). 891 | 892 | This operation MUST fail if there are service instances associated with this service broker. 893 | 894 | #### Route 895 | 896 | `DELETE /v1/service_brokers/:broker_id` 897 | 898 | `:broker_id` MUST be the ID of an existing service broker. 899 | 900 | ## Service Instance Management 901 | 902 | ### Provisioning a Service Instance 903 | 904 | Creation of a `service instance` resource entity MUST comply with [creating a resource entity](#creating-a-resource-entity). 905 | 906 | #### Route 907 | 908 | `POST /v1/service_instances` 909 | 910 | #### Request Body 911 | 912 | ##### Service Instance Object 913 | 914 | ```json 915 | { 916 | "name": "my-service-instance", 917 | "service_plan_id": "sm-service-plan-id-here", 918 | "parameters": { 919 | "parameter1": "value1", 920 | "parameter2": "value2" 921 | }, 922 | "labels": { 923 | "context_id": [ 924 | "bvsded31-c303-123a-aab9-8crar19e1218" 925 | ] 926 | } 927 | } 928 | ``` 929 | 930 | | Request field | Type | Description | 931 | | -------------- | ---- | ----------- | 932 | | name* | string | A non-empty instance name. | 933 | | service_plan_id* | string | MUST be the ID of a Service Plan from SM database. | 934 | | parameters | object | Configuration parameters for the Service Instance. | 935 | | labels | collection of [labels](#labels-object) | Additional data associated with the resource entity. MAY be an empty array. | 936 | 937 | \* Fields with an asterisk are REQUIRED. 938 | 939 | **Note:** Service Manager MUST also handle [mitigating orphans](#mitigating-orphans) in the context of service instances. 940 | 941 | ### Fetching a Service Instance 942 | 943 | Fetching of a `service instance` resource entity MUST comply with [fetching a resource entity](#fetching-a-resource-entity). 944 | 945 | The Service Manager MAY choose to provide cached data and not to [fetch the data from the upstream broker](https://github.com/openservicebrokerapi/servicebroker/blob/v2.14/spec.md#fetching-a-service-instance). 946 | 947 | #### Route 948 | 949 | `GET /v1/service_instances/:service_instance_id` 950 | 951 | `:service_instance_id` MUST be the ID of a previously provisioned service instance. 952 | 953 | #### Response Body 954 | 955 | ##### Service Instance Object 956 | 957 | ```json 958 | { 959 | "id": "c5aa6823-6313-4b91-bd95-79eef15c45ea", 960 | "name": "my-instance", 961 | "context": { 962 | "account": "my-account" 963 | }, 964 | "created_at": "2020-04-27T11:53:29.889164Z", 965 | "updated_at": "2020-04-27T11:53:29.889164Z", 966 | "labels": { 967 | "context_id": [ 968 | "3eecc074-950a-468e-9113-52f3e6a72660" 969 | ] 970 | }, 971 | "service_plan_id": "c6085b9d-a2f1-444b-a052-83c5c1456850", 972 | "platform_id": "549cecfe-3807-4009-b6cb-c258217750b4", 973 | "ready": true, 974 | "usable": true 975 | } 976 | ``` 977 | 978 | | Response field | Type | Description | 979 | | -------------- | ---- | ----------- | 980 | | id | string | Service Instance ID. | 981 | | name | string | Service Instance name. | 982 | | service_plan_id | string | The ID of the Service Plan. | 983 | | platform_id | string | ID of the Platform that owns this instance or `null` if the Service Manager owns it. | 984 | | context | object | Contextual data for the resource. | 985 | | dashboard_url | string | The URL of a web-based management user interface for the Service Instance; we refer to this as a service dashboard. | 986 | | labels | collection of [labels](#labels-object) | Additional data associated with the resource entity. MAY be an empty array. | 987 | | created_at | string | The time of the creation [in ISO 8601 format](#data-formats). | 988 | | updated_at | string | The time of the last update [in ISO 8601 format](#data-formats). | 989 | | usable | boolean | If the instance is `usable` or not (as per the OSB spec `instance_usable`) | 990 | | ready | boolean | Whether the resource is ready or not. | 991 | 992 | ### Fetching a Service Instance Parameters 993 | 994 | Service Manager fetches the data from the upstream broker. 995 | 996 | #### Route 997 | 998 | `GET /v1/service_instances/:service_instance_id/parameters` 999 | 1000 | `:service_instance_id` MUST be the ID of a previously provisioned service instance. 1001 | The instances_retrievable feature must be enabled for the service offering in broker catalog. 1002 | 1003 | #### Response Body 1004 | 1005 | ##### Service Instance Parameters Object 1006 | 1007 | ```json 1008 | { 1009 | "param1":"value1", 1010 | "param2":"value2" 1011 | } 1012 | ``` 1013 | 1014 | #### Response 1015 | 1016 | | Status Code | Description | 1017 | | ----------- | ----------- | 1018 | | 200 OK | MUST be returned if the request execution was successful. | 1019 | | 404 Not Found | MUST be returned if the requested resource is missing, the creation operation is still in progress, or if the user is not authorized to access this resource. | 1020 | | 400 Bad Request | MUST be returned if the broker doesn't support fetching of instances for this service offering or if request was sent with the value true for query param: async. (if the operation is asynchronous) | 1021 | | 502 Bad Gateway | MUST be returned if there was a failure to parse the parameters of the service instance returned from a broker. | 1022 | 1023 | ### Listing Service Instances 1024 | 1025 | Listing `service instances` MUST comply with [listing all resource entities of a resource type](#listing-all-resource-entities-of-a-resource-type). 1026 | 1027 | The Service Manager MAY choose to provide cached data and not to [fetch the data from the upstream brokers](https://github.com/openservicebrokerapi/servicebroker/blob/v2.14/spec.md#fetching-a-service-instance). 1028 | 1029 | #### Route 1030 | 1031 | `GET /v1/service_instances` 1032 | 1033 | ### Response Body 1034 | 1035 | ```json 1036 | { 1037 | "num_items": 1, 1038 | "items": [ 1039 | { 1040 | "id": "c5aa6823-6313-4b91-bd95-79eef15c45ea", 1041 | "name": "my-instance", 1042 | "created_at": "2020-04-27T11:53:29.889164Z", 1043 | "updated_at": "2020-04-27T11:53:29.889164Z", 1044 | "labels": { 1045 | "context_id": [ 1046 | "3eecc074-950a-468e-9113-52f3e6a72660" 1047 | ] 1048 | }, 1049 | "service_plan_id": "c6085b9d-a2f1-444b-a052-83c5c1456850", 1050 | "platform_id": "549cecfe-3807-4009-b6cb-c258217750b4", 1051 | "ready": true, 1052 | "usable": true 1053 | } 1054 | ] 1055 | } 1056 | ``` 1057 | 1058 | ### Patching a Service Instance 1059 | 1060 | Patching of a `service instance` resource entity MUST comply with [patching a resource entity](#patching-a-resource-entity). 1061 | 1062 | #### Route 1063 | 1064 | `PATCH /v1/service_instances/:service_instance_id` 1065 | 1066 | `:service_instance_id` The ID of a previously provisioned service instance. 1067 | 1068 | #### Request Body 1069 | 1070 | See [Provisioning a Service Instance](#provisioning-a-service-instance) and [Patching Labels](#patching-labels). 1071 | 1072 | **Note:** Patching parameters works as described in the [OSB specification](https://github.com/openservicebrokerapi/servicebroker/blob/v2.14/spec.md#updating-a-service-instance) in section "*Updating a Service Instance*". 1073 | 1074 | ### Deleting a Service Instance 1075 | 1076 | Deletion of a `service instance` resource entity MUST comply with [deleting a resource entity](#deleting-a-resource-entity). 1077 | 1078 | #### Route 1079 | 1080 | `DELETE /v1/service_instances/:service_instance_id` 1081 | 1082 | `:service_instance_id` MUST be the ID of a previously provisioned service instance. 1083 | 1084 | ## Service Binding Management 1085 | 1086 | ### Creating a Service Binding 1087 | 1088 | Creation of a `service binding` resource entity MUST comply with [creating a resource entity](#creating-a-resource-entity). 1089 | 1090 | #### Route 1091 | 1092 | `POST /v1/service_bindings` 1093 | 1094 | #### Request Body 1095 | 1096 | ##### Service Binding Object 1097 | 1098 | ```json 1099 | { 1100 | "name": "my-service-binding", 1101 | "service_instance_id": "asd124bc21-df28-4891-8d91-46334e04600d", 1102 | "parameters": { 1103 | "parameter1": "value1", 1104 | "parameter2": "value2" 1105 | }, 1106 | "labels": { 1107 | "context_id": [ 1108 | "bvsded31-c303-123a-aab9-8crar19e1218" 1109 | ] 1110 | } 1111 | } 1112 | ``` 1113 | 1114 | | Request field | Type | Description | 1115 | | -------------- | ---- | ----------- | 1116 | | name* | string | A non-empty instance name. | 1117 | | service_instance_id* | string | MUST be the ID of a Service Instance from SM database. | 1118 | | parameters | object | Configuration parameters for the Service Binding. Service Brokers SHOULD ensure that the client has provided valid configuration parameters and values for the operation. | 1119 | | labels | collection of [labels](#labels-object) | Additional data associated with the resource entity. MAY be an empty array. | 1120 | 1121 | \* Fields with an asterisk are REQUIRED. 1122 | 1123 | **Note:** Service Manager MUST also handle [mitigating orphans](#mitigating-orphans) in the context of service bindings. 1124 | 1125 | ### Fetching a Service Binding 1126 | 1127 | Fetching of a `service binding` resource entity MUST comply with [fetching a resource entity](#fetching-a-resource-entity). 1128 | 1129 | The Service Manager MAY choose to provide cached data and not to [fetch the data from the upstream broker](https://github.com/openservicebrokerapi/servicebroker/blob/v2.14/spec.md#fetching-a-service-binding). 1130 | 1131 | #### Route 1132 | 1133 | `GET /v1/service_bindings/:service_binding_id` 1134 | 1135 | `:service_binding_id` MUST be the ID of a previously created service binding. 1136 | 1137 | #### Response Body 1138 | 1139 | ##### Service Binding Object 1140 | 1141 | ```json 1142 | { 1143 | "id": "138001bc-80bd-4d67-bf3a-956e4w543c3c", 1144 | "name": "my-service-binding", 1145 | "service_instance_id": "asd124bc21-df28-4891-8d91-46334e04600d", 1146 | "context": { 1147 | "account": "my-account" 1148 | }, 1149 | "credentials": { 1150 | "creds-key-63": "creds-val-63", 1151 | "url": "https://my.example.org" 1152 | }, 1153 | "labels": { 1154 | "context_id": [ 1155 | "bvsded31-c303-123a-aab9-8crar19e1218" 1156 | ] 1157 | }, 1158 | "created_at": "2016-06-08T16:41:22.213Z", 1159 | "updated_at": "2016-06-08T16:41:26.0Z", 1160 | "ready": true 1161 | } 1162 | ``` 1163 | 1164 | | Response field | Type | Description | 1165 | | -------------- | ---- | ----------- | 1166 | | id | string | The Service Binding ID. | 1167 | | name | string | The Service Binding name. | 1168 | | service_instance_id | string | The Service Instance ID. | 1169 | | context | object | Contextual data for the resource. | 1170 | | credentials | object | Credentials to access the binding. | 1171 | | labels | collection of [labels](#labels-object) | Additional data associated with the resource entity. MAY be an empty object. | 1172 | | created_at | string | The time of the creation [in ISO 8601 format](#data-formats). | 1173 | | updated_at | string | The time of the last update [in ISO 8601 format](#data-formats). | 1174 | | ready | boolean | Whether the resource is ready or not. | 1175 | 1176 | ### Fetching a Service Binding Parameters 1177 | 1178 | Service Manager fetches the data from the upstream broker. 1179 | 1180 | #### Route 1181 | 1182 | `GET /v1/service_bindings/:service_binding_id/parameters` 1183 | 1184 | `:service_binding_id` MUST be the ID of a previously created service binding. 1185 | The bindings_retrievable feature must be enabled for the service offering in broker catalog. 1186 | 1187 | #### Response Body 1188 | 1189 | ##### Service Binding Object 1190 | 1191 | ```json 1192 | { 1193 | "param1":"value1", 1194 | "param2":"value2" 1195 | } 1196 | ``` 1197 | #### Response 1198 | 1199 | | Status Code | Description | 1200 | | ----------- | ----------- | 1201 | | 200 OK | MUST be returned if the request execution was successful. | 1202 | | 404 Not Found | MUST be returned if the requested resource is missing, if the creation operation is still in progress, or if the user is not authorized to access this resource. | 1203 | | 400 Bad Request | MUST be returned if the broker doesn't support fetching of bindings for this service offering or if request was sent with the value true for the query param: async. (if the operation is asynchronous). | 1204 | | 502 Bad Gateway | MUST be returned if there was a failure to parse the parameters of the service binding returned from a broker. | 1205 | 1206 | ### Listing Service Bindings 1207 | 1208 | Listing `service bindings` MUST comply with [listing all resource entities of a resource type](#listing-all-resource-entities-of-a-resource-type). 1209 | 1210 | The Service Manager MAY choose to provide cached data and not to [fetch the data from the upstream brokers](https://github.com/openservicebrokerapi/servicebroker/blob/v2.14/spec.md#fetching-a-service-binding). 1211 | 1212 | #### Route 1213 | 1214 | `GET /v1/service_bindings` 1215 | 1216 | #### Response Body 1217 | 1218 | ```json 1219 | { 1220 | "num_items": 1, 1221 | "items": [ 1222 | { 1223 | "id": "138001bc-80bd-4d67-bf3a-956e4w543c3c", 1224 | "name": "my-service-binding", 1225 | "service_instance_id": "asd124bc21-df28-4891-8d91-46334e04600d", 1226 | "context": {"account": "my-account"}, 1227 | "credentials": { 1228 | "creds-key-63": "creds-val-63", 1229 | "url": "https://my.example.org" 1230 | }, 1231 | "labels": { 1232 | "context_id": [ 1233 | "bvsded31-c303-123a-aab9-8crar19e1218" 1234 | ] 1235 | }, 1236 | "created_at": "2016-06-08T16:41:22.213Z", 1237 | "updated_at": "2016-06-08T16:41:26.0Z", 1238 | "ready": true 1239 | } 1240 | ] 1241 | } 1242 | ``` 1243 | 1244 | ## Patching a Service Binding 1245 | 1246 | Updating of a `service binding` resource entity MUST comply with [patching a resource entity](#patching-a-resource-entity). 1247 | 1248 | Only the name and the labels can be changed. 1249 | 1250 | #### Route 1251 | 1252 | `PATCH /v1/service_bindings/:service_binding_id` 1253 | 1254 | `:service_binding_id` The ID of a previously created service binding. 1255 | 1256 | #### Request Body 1257 | 1258 | | Request field | Type | Description | 1259 | | -------------- | ---- | ----------- | 1260 | | name | string | A non-empty binding name. | 1261 | | parameters | object | Configuration parameters for the Service Binding. Service Brokers SHOULD ensure that the client has provided valid configuration parameters and values for the operation. | 1262 | | labels | array of label patches | See [Patching Labels](#patching-labels). | 1263 | 1264 | \* Fields with an asterisk are REQUIRED. 1265 | 1266 | ### Deleting a Service Binding 1267 | 1268 | Deletion of a `service binding` resource entity MUST comply with [deleting a resource entity](#deleting-a-resource-entity). 1269 | 1270 | #### Route 1271 | 1272 | `DELETE /v1/service_bindings/:service_binding_id` 1273 | 1274 | `:service_binding_id` MUST be the ID of a previously created service binding. 1275 | 1276 | ## Service Offering Management 1277 | 1278 | As per the OSB API terminology a service offering represents the advertisement of a service that a service broker supports. Service Manager MUST expose a management API of the service offerings offered by the registered service brokers. 1279 | 1280 | ### Fetching a Service Offering 1281 | 1282 | Fetching of a `service offering` resource entity MUST comply with [fetching a resource entity](#fetching-a-resource-entity). 1283 | 1284 | #### Route 1285 | 1286 | `GET /v1/service_offerings/:service_offering_id` 1287 | 1288 | `:service_offering_id` MUST be the ID of a service offering. 1289 | 1290 | #### Response Body 1291 | 1292 | ##### Service Offering Object 1293 | 1294 | ```json 1295 | { 1296 | "id": "64314767-b572-4145-a17a-d2e3a28405bb", 1297 | "name": "fake-service-test", 1298 | "description": "Provides an overview of any service instances and bindings that have been created by a platform.", 1299 | "catalog_id": "33ceba5779bfa320a1ef0694d98069df", 1300 | "catalog_name": "fake-service-test", 1301 | "broker_id": "ff574286-ed90-4f45-a059-612a47eebe93", 1302 | "allow_context_updates": false, 1303 | "bindable": true, 1304 | "bindings_retrievable": true, 1305 | "instances_retrievable": true, 1306 | "plan_updateable": true, 1307 | "metadata": { 1308 | "shareable": true 1309 | }, 1310 | "tags": [ 1311 | "overview-broker" 1312 | ], 1313 | "created_at": "2020-04-27T11:16:49.112474Z", 1314 | "updated_at": "2020-04-27T11:16:49.307321Z", 1315 | "ready": true 1316 | } 1317 | ``` 1318 | 1319 | | Response field | Type | Description | 1320 | | -------------- | ---- | ----------- | 1321 | | id | string | Internal Service Offering ID. | 1322 | | name | string | Service Offering name. | 1323 | | description | string | Description for this Service Offering. | 1324 | | catalog_id | string | The service catalog id for this Service Offering. | 1325 | | catalog_name | string | The service catalog name for this Service Offering. | 1326 | | broker_id | string | The SM database id of the Service Broker to which this Service Offering belongs. | 1327 | | allow_context_updates | boolean | Whether context updates are supported for this Service Offering. | 1328 | | bindable | boolean | Whether service bindings are supported for this Service Offerng. | 1329 | | bindings_retrievable | boolean | Whether the broker supports fetching of bindings for this Service Offering. | 1330 | | instances_retrievable | boolean | Whether the broker supports fetching of instances for this Service Offering. | 1331 | | plan_updateable | boolean | Whether the broker supports plan updates for this Service Offering. | 1332 | | metadata | object | OSB metadata for this Service Offering. | 1333 | | tags | array of objects | OSB tags for this Service Offering. | 1334 | | labels | collection of [labels](#labels-object) | Additional data associated with the resource entity. MAY be an empty object. | 1335 | | created_at | string | The time of the creation [in ISO 8601 format](#data-formats). | 1336 | | updated_at | string | The time of the last update [in ISO 8601 format](#data-formats). | 1337 | | ready | boolean | Whether the resource is ready or not. | 1338 | 1339 | ### Listing Service Offerings 1340 | 1341 | Listing `service offerings` MUST comply with [listing all resource entities of a resource type](#listing-all-resource-entities-of-a-resource-type). 1342 | 1343 | #### Route 1344 | 1345 | `GET /v1/service_offerings` 1346 | 1347 | #### Response Body 1348 | 1349 | ```json 1350 | { 1351 | "token": "token1234", 1352 | "num_items": 523, 1353 | "items":[ 1354 | { 1355 | "id": "64314767-b572-4145-a17a-d2e3a28405bb", 1356 | "name": "fake-service-test", 1357 | "description": "Provides an overview of any service instances and bindings that have been created by a platform.", 1358 | "catalog_id": "33ceba5779bfa320a1ef0694d98069df", 1359 | "catalog_name": "fake-service-test", 1360 | "broker_id": "ff574286-ed90-4f45-a059-612a47eebe93", 1361 | "allow_context_updates": false, 1362 | "bindable": true, 1363 | "bindings_retrievable": true, 1364 | "instances_retrievable": true, 1365 | "plan_updateable": true, 1366 | "metadata": { 1367 | "shareable": true 1368 | }, 1369 | "tags": [ 1370 | "overview-broker" 1371 | ], 1372 | "created_at": "2020-04-27T11:16:49.112474Z", 1373 | "updated_at": "2020-04-27T11:16:49.307321Z", 1374 | "ready": true 1375 | }, 1376 | ... 1377 | ] 1378 | } 1379 | ``` 1380 | 1381 | ### Patching a Service Offering 1382 | 1383 | Patching of a `service offering` resource entity MUST comply with [patching a resource entity](#patching-a-resource-entity). 1384 | 1385 | Only patching of labels is supported. 1386 | 1387 | #### Route 1388 | 1389 | `PATCH /v1/service_offerings/:service_offering_id` 1390 | 1391 | `:service_offering_id` The ID of an existing Service Offering. 1392 | 1393 | ##### Request Body 1394 | 1395 | See [Patching Labels](#patching-labels). 1396 | 1397 | ## Service Plan Management 1398 | 1399 | As per the OSB API terminology, a service plan is representation of the costs and benefits for a given variant of the service, potentially as a tier that a service broker offers. Service Manager MUST expose a management API of the service plans offered by services of the registered service brokers. 1400 | 1401 | ### Fetching a Service Plan 1402 | 1403 | Fetching of a `service plan` resource entity MUST comply with [fetching a resource entity](#fetching-a-resource-entity). 1404 | 1405 | #### Route 1406 | 1407 | `GET /v1/service_plans/:service_plan_id` 1408 | 1409 | `:service_plan_id` MUST be the ID of a plan. 1410 | 1411 | #### Response Body 1412 | 1413 | ##### Service Plan Object 1414 | 1415 | ```json 1416 | { 1417 | "id": "2970eb1d-0bc7-4fb1-b435-08b00afdabd8", 1418 | "name": "fake-plan-2", 1419 | "description": "Another simple plan.", 1420 | "catalog_id": "a167b29fa60b94235ce5a426fa14ac48", 1421 | "catalog_name": "fake-plan-2", 1422 | "free": true, 1423 | "bindable": true, 1424 | "plan_updateable": true, 1425 | "maximum_polling_duration": 60, 1426 | "service_offering_id": "64314767-b572-4145-a17a-d2e3a28405bb", 1427 | "metadata": { 1428 | "supportedPlatforms": [ 1429 | "kubernetes" 1430 | ] 1431 | }, 1432 | "created_at": "2020-04-27T11:16:49.112474Z", 1433 | "updated_at": "2020-04-27T11:16:49.321865Z", 1434 | "ready": true 1435 | } 1436 | ``` 1437 | 1438 | | Response field | Type | Description | 1439 | | -------------- | ---- | ----------- | 1440 | | id | string | Internal Service Plan ID. | 1441 | | name | string | Service Plan name. | 1442 | | description | string | Description for this Service Plan. | 1443 | | catalog_id | string | The service catalog id for this Service Plan. | 1444 | | catalog_name | string | The service catalog name for this Service Plan. | 1445 | | free | boolean | Whether the Service Plan is free or not. | 1446 | | bindable | boolean | Specifies whether Service Instances of the Service Plan can be bound to applications. This field is OPTIONAL. If specified, this takes precedence over the bindable attribute of the Service Offering. If not specified, the default is derived from the Service Offering. | 1447 | | plan_updateable | boolean | Whether the Plan supports upgrade/downgrade/sidegrade to another version. This field is OPTIONAL. If specificed, this takes precedence over the Service Offering's plan_updateable field. If not specified, the default is derived from the Service Offering. Please note that the attribute is intentionally misspelled as `plan_updateable` for legacy reasons. | 1448 | | maximum_polling_duration | integer | The maximum duration that SM would try polling. | 1449 | | service_offering_id | string | The SM database id of the Service Offering to which this Service Plan belongs. | 1450 | | metadata | object | OSB metadata for this Service Plan. | 1451 | | labels | collection of [labels](#labels-object) | Additional data associated with the resource entity. MAY be an empty object. | 1452 | | created_at | string | The time of the creation [in ISO 8601 format](#data-formats). | 1453 | | updated_at | string | The time of the last update [in ISO 8601 format](#data-formats). | 1454 | | ready | boolean | Whether the resource is ready or not. | 1455 | 1456 | ### Listing Service Plans 1457 | 1458 | Listing `service plans` MUST comply with [listing all resource entities of a resource type](#listing-all-resource-entities-of-a-resource-type). 1459 | 1460 | #### Route 1461 | 1462 | `GET /v1/service_plans` 1463 | 1464 | #### Response Body 1465 | 1466 | ```json 1467 | { 1468 | "token": "token1234", 1469 | "num_items": 732, 1470 | "items": [ 1471 | { 1472 | "id": "2970eb1d-0bc7-4fb1-b435-08b00afdabd8", 1473 | "name": "fake-plan-2", 1474 | "description": "Another simple plan.", 1475 | "catalog_id": "a167b29fa60b94235ce5a426fa14ac48", 1476 | "catalog_name": "fake-plan-2", 1477 | "free": true, 1478 | "bindable": true, 1479 | "plan_updateable": true, 1480 | "maximum_polling_duration": 60, 1481 | "service_offering_id": "64314767-b572-4145-a17a-d2e3a28405bb", 1482 | "metadata": { 1483 | "supportedPlatforms": [ 1484 | "kubernetes" 1485 | ] 1486 | }, 1487 | "created_at": "2020-04-27T11:16:49.112474Z", 1488 | "updated_at": "2020-04-27T11:16:49.321865Z", 1489 | "ready": true 1490 | }, 1491 | ... 1492 | ] 1493 | } 1494 | ``` 1495 | 1496 | ### Patching a Service Plan 1497 | 1498 | Patching of a `service plan` resource entity MUST comply with [patching a resource entity](#patching-a-resource-entity). 1499 | 1500 | Only patching of labels is supported. 1501 | 1502 | #### Route 1503 | 1504 | `PATCH /v1/service_plans/:service_plan_id` 1505 | 1506 | `:service_plan_id` The ID of an existing Service Plan. 1507 | 1508 | ##### Request Body 1509 | 1510 | See [Patching Labels](#patching-labels). 1511 | 1512 | ## Service Visibility Management 1513 | 1514 | Visibilities in the Service Manager are used to manage which Platform sees which Service Plan. If applicable, labels MAY be attached to a visibility to further scope the access of the plan inside the Platform. 1515 | 1516 | Visibilities are automatically deleted when the referenced Platform is deregistered or when the referenced Service Plan becomes unavailable. 1517 | 1518 | ### Creating a Visibility 1519 | 1520 | Creation of a `visibility` resource entity MUST comply with [creating a resource entity](#creating-a-resource-entity). 1521 | 1522 | #### Route 1523 | 1524 | `POST /v1/visibilities` 1525 | 1526 | #### Request Body 1527 | 1528 | ```json 1529 | { 1530 | "platform_id": "038001bc-80bd-4d67-bf3a-956e4d545e3c", 1531 | "service_plan_id": "fe173a83-df28-4891-8d91-46334e04600d", 1532 | "labels": { 1533 | "label1": ["value1"] 1534 | } 1535 | } 1536 | ``` 1537 | 1538 | | Name | Type | Description | 1539 | | ---- | ---- | ----------- | 1540 | | platform_id | string | If present, MUST be the ID of an existing Platform or `null`. If missing or `null`, this means that the Service Plan is visible to all Platforms. | 1541 | | service_plan_id* | string | This MUST be the ID of an existing Service Plan. | 1542 | | labels | collection of [labels](#labels-object) | Additional data associated with the resource entity. MAY be an empty object. | 1543 | 1544 | \* Fields with an asterisk are REQUIRED. 1545 | 1546 | ### Fetching a Visibility 1547 | 1548 | Fetching of a `visibility` resource entity MUST comply with [fetching a resource entity](#fetching-a-resource-entity). 1549 | 1550 | #### Request 1551 | 1552 | ##### Route 1553 | 1554 | `GET /v1/visibilities/:visibility_id` 1555 | 1556 | `:visibility_id` MUST be the ID of a previously created visibility. 1557 | 1558 | #### Response 1559 | 1560 | ##### Visibility Object 1561 | 1562 | ```json 1563 | { 1564 | "id": "36931aaf-62a7-4019-a708-0e9abf7e7a8f", 1565 | "platform_id": "038001bc-80bd-4d67-bf3a-956e4d545e3c", 1566 | "service_plan_id": "fe173a83-df28-4891-8d91-46334e04600d", 1567 | "created_at": "2016-06-08T16:41:22.104Z", 1568 | "updated_at": "2016-06-08T16:41:26.734Z", 1569 | "labels": { 1570 | "label1": ["value1"] 1571 | }, 1572 | "ready": true 1573 | } 1574 | ``` 1575 | 1576 | | Response Field | Type | Description | 1577 | | -------------- | ---- | ----------- | 1578 | | id | string | ID of the visibility. | 1579 | | platform_id | string | ID of the Platform for this Visibility or `null` if this Visibility is valid for all Platforms. | 1580 | | service_plan_id | string | ID of the Service Plan for this Visibility. | 1581 | | created_at | string | The time of creation [in ISO 8601 format](#data-formats). | 1582 | | updated_at | string | The time of the last update [in ISO 8601 format](#data-formats). | 1583 | | labels | collection of [labels](#labels-object) | Additional data associated with the Visibility. MAY be an empty object. | 1584 | | ready | boolean | Whether the resource is ready or not. | 1585 | 1586 | ### Listing All Visibilities 1587 | 1588 | Listing `visibilities` MUST comply with [listing all resource entities of a resource type](#listing-all-resource-entities-of-a-resource-type). 1589 | 1590 | #### Request 1591 | 1592 | ##### Route 1593 | 1594 | `GET /v1/visibilities` 1595 | 1596 | ##### Response Body 1597 | 1598 | ```json 1599 | { 1600 | "num_item": 2, 1601 | "items": [ 1602 | { 1603 | "id": "36931aaf-62a7-4019-a708-0e9abf7e7a8f", 1604 | "platform_id": "038001bc-80bd-4d67-bf3a-956e4d545e3c", 1605 | "service_plan_id": "fe173a83-df28-4891-8d91-46334e04600d", 1606 | "created_at": "2016-06-08T16:41:22.104Z", 1607 | "updated_at": "2016-06-08T16:41:26.734Z", 1608 | "labels": { 1609 | "label1": ["value1"] 1610 | }, 1611 | "ready": true 1612 | }, 1613 | { 1614 | "id": "3aaed233-7fb0-4441-becb-4a09f33265d8", 1615 | "platform_id": null, 1616 | "service_plan_id": "83ae38ae-ad02-4fe9-ae39-406a59cdf7e6", 1617 | "created_at": "2016-06-09T16:41:22.104Z", 1618 | "updated_at": "2016-06-09T16:41:26.734Z", 1619 | "labels": { 1620 | 1621 | }, 1622 | "ready": true 1623 | } 1624 | ] 1625 | } 1626 | ``` 1627 | 1628 | ### Patching a Visibility 1629 | 1630 | Patching of a `visibiliy` resource entity MUST comply with [patching a resource entity](#patching-a-resource-entity). 1631 | 1632 | #### Route 1633 | 1634 | `PATCH /v1/visibilities/:visibility_id` 1635 | 1636 | `:visibility_id` MUST be the ID of a previously created visibility. 1637 | 1638 | #### Request Body 1639 | 1640 | See [Creating a Visibility](#creating-a-visibility) and [Patching Labels](#patching-labels). 1641 | 1642 | ### Deleting a Visibility 1643 | 1644 | Deletion of a `visibility` resource entity MUST comply with [deleting a resource entity](#deleting-a-resource-entity). 1645 | 1646 | #### Request 1647 | 1648 | ##### Route 1649 | 1650 | `DELETE /v1/visibilities/:visibility_id` 1651 | 1652 | `:visibility_id` MUST be the ID of a previously created Visibility. 1653 | 1654 | ## Operation Management 1655 | 1656 | Operations in the Service Manager are used to represent addtional details in regards to REST requests. They provide details whether the request succeeded, failed or is in progress, whether the request reached a state after which it is retryable, whether automatic deletion/orphan mitigation is required, etc. 1657 | 1658 | Operation objects are meant for clients. They SHOULD NOT convey any Service Manager implementation or process details or use internal terminology. Status description should be meaningful to the majority of end-users. 1659 | 1660 | 1661 | ### Listing All Operations 1662 | 1663 | Listing `operations` MUST comply with [listing all resource entities of a resource type](#listing-all-resource-entities-of-a-resource-type). 1664 | 1665 | #### Request 1666 | 1667 | ##### Route 1668 | 1669 | `GET /v1/operations` 1670 | 1671 | ##### Response Body 1672 | 1673 | ```json 1674 | { 1675 | "num_item": 2, 1676 | "items": [ 1677 | { 1678 | "operation_id":"c7880869-e1e8-403a-b57c-1396f5c89239", 1679 | "description": "polling instance last op...", 1680 | "correlation_id":"a2480869-d1e6-215c-d42a-1256f5c54321", 1681 | "type":"CREATE", 1682 | "state":"IN_PROGRESS", 1683 | "created_at":"2019-07-09T17:48:01.45Z", 1684 | "updated_at":"2019-07-09T17:55:02.33Z", 1685 | "resource_id":"a67ebb30-a71a-4c23-81c6-f79fae6fe457", 1686 | "resource_type":"/v1/service_instances", 1687 | "reschedule": true, 1688 | "reschedule_timestamp": "2019-07-09T17:55:02.33Z", 1689 | "ready": true 1690 | }, 1691 | { 1692 | "id": "203ec548-f7e8-4405-8253-fcc8d3411353", 1693 | "description": "create platform...", 1694 | "type": "create", 1695 | "state": "succeeded", 1696 | "resource_id": "7825db3c-4fd3-4c04-805f-cf791c3fe2da", 1697 | "resource_type": "/v1/platforms", 1698 | "platform_id": "2425db3c-4fd3-4c04-805f-cf791c3fe2cb", 1699 | "deletion_scheduled": "0001-01-01T00:00:00Z", 1700 | "reschedule": false, 1701 | "reschedule_timestamp": "0001-01-01T00:00:00Z", 1702 | "correlation_id": "02b3af2e-7bb1-42f5-a998-725b9b9eca90", 1703 | "labels": { 1704 | "account": [ 1705 | "account-id" 1706 | ] 1707 | }, 1708 | "created_at": "2020-04-27T11:17:58.725628Z", 1709 | "updated_at": "2020-04-27T11:17:58.90543Z", 1710 | "ready": true, 1711 | "transitive_resources": [ 1712 | { 1713 | "id": "d4cbf5da-661c-44f6-a9d3-306c04c59add", 1714 | "operation_type": "create", 1715 | "type": "/v1/visibilities" 1716 | }, 1717 | { 1718 | "id": "910fc7d5-91ce-4190-b722-0523a02c31c5", 1719 | "operation_type": "create", 1720 | "type": "/v1/visibilities" 1721 | }, 1722 | { 1723 | "id": "4ab5f93d-c2bf-472e-abcb-ae798062f6d5", 1724 | "operation_type": "create", 1725 | "type": "/v1/visibilities" 1726 | }, 1727 | { 1728 | "id": "d4cbf5da-661c-44f6-a9d3-306c04c59add", 1729 | "operation_type": "update", 1730 | "type": "/v1/visibilities" 1731 | }, 1732 | { 1733 | "id": "de140874-694a-4579-83ed-139ab3a610b9", 1734 | "operation_type": "create", 1735 | "type": "/v1/notifications" 1736 | }, 1737 | { 1738 | "id": "910fc7d5-91ce-4190-b722-0523a02c31c5", 1739 | "operation_type": "update", 1740 | "type": "/v1/visibilities" 1741 | }, 1742 | { 1743 | "id": "cb9fc3fc-479b-4060-99b9-15a72cb3ffa6", 1744 | "operation_type": "create", 1745 | "type": "/v1/notifications" 1746 | }, 1747 | { 1748 | "id": "4ab5f93d-c2bf-472e-abcb-ae798062f6d5", 1749 | "operation_type": "update", 1750 | "type": "/v1/visibilities" 1751 | }, 1752 | { 1753 | "id": "e591ff90-6352-4e7d-b6c6-4434452e2800", 1754 | "operation_type": "create", 1755 | "type": "/v1/notifications" 1756 | } 1757 | ] 1758 | } 1759 | ] 1760 | } 1761 | ``` 1762 | 1763 | ## Information Management 1764 | 1765 | The Service Manager exposes publicly available information that can be used when accessing its APIs. 1766 | 1767 | ### Request 1768 | 1769 | #### Route 1770 | 1771 | `GET /v1/info` 1772 | 1773 | ### Response 1774 | 1775 | | Status Code | Description | 1776 | | ----------- | ----------- | 1777 | | 200 OK | MUST be returned upon successful processing of this request. The expected response body is below. | 1778 | 1779 | Responses with any other status code will be interpreted as a failure. The response can include a user-facing message in the `description` field. For details see [Errors](#errors). 1780 | 1781 | #### Body 1782 | 1783 | ```json 1784 | { 1785 | "token_issuer_url": "https://example.com" 1786 | } 1787 | ``` 1788 | 1789 | | Name | Type | Description | 1790 | | ---- | ---- | ----------- | 1791 | | token_issuer_url* | string | URL of the token issuer. The token issuer MUST have a public endpoint `/.well-known/openid-configuration` as specified by the [OpenID Provider Configuration](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig). | 1792 | 1793 | \* Fields with an asterisk are REQUIRED. 1794 | 1795 | ## OSB Management 1796 | 1797 | The OSB Management API is an implementation of the [OSB API specification](https://github.com/openservicebrokerapi/servicebroker). It enables the Service Manager to act as a central service broker and be registered as one in the Platforms that are associated with it (meaning the Platforms that are registered in the Service Manager). The Service Manager also takes care of delegating the OSB calls to the registered brokers (meaning brokers that are registered in the Service Manager) that should process the request. As such, the Service Manager acts as a Platform for the actual (registered) brokers. 1798 | 1799 | ### Request 1800 | 1801 | The OSB Management API prefixes the routes specified in the OSB spec with `/v1/osb/:broker_id`. 1802 | 1803 | `:broker_id` is the ID of the broker that the OSB call is targeting. The Service Manager MUST forward the call to this broker. The `broker_id` MUST be a globally unique non-empty string. 1804 | 1805 | When a request is sent to the OSB Management API, after forwarding the call to the actual broker but before returning the response, the Service Manager MAY alter the headers and the body of the response. For example, in the case of `/v1/osb/:broker_id/v2/catalog` request, the Service Manager MAY, amongst other things, add additional plans (reference plan) to the catalog. 1806 | 1807 | In its role of a Platform for the registered brokers, the Service Manager MAY define its own format for `Context Object` and `Originating Identity Header` similar but not limited to those specified in the [OSB spec profiles page](https://github.com/openservicebrokerapi/servicebroker/blob/master/profile.md). 1808 | For example, the `Context Object` SHOULD contain an entry `instance_name` that provides the name of the Service Instance. 1809 | 1810 | ## Credentials Object 1811 | 1812 | This specification does not limit how the Credentials Object should look like as different authentication mechanisms can be used. Depending on the used authentication mechanism, additional fields holding the actual credentials MAY be included. 1813 | 1814 | **Note:** The following structure of the credentials object does not apply for Service Binding credentials. Service Binding credentials are provided by the Service Broker and MAY be free form as long as they comply with the OSB specification. 1815 | 1816 | | Field | Type | Description | 1817 | | ----- | ---- | ----------- | 1818 | | basic | [basic credentials](#basic-credentials-object) | Credentials for basic authentication | 1819 | | token | string | Bearer token | 1820 | | tls | [client certificate credentials](#client-certificate-credentials-object) | Credentials for client certificate authentication | 1821 | 1822 | _Exactly one_ of the properties `basic` or `token` MUST be provided. 1823 | 1824 | ### Basic Credentials Object 1825 | 1826 | | Field | Type | Description | 1827 | | ----- | ---- | ----------- | 1828 | | username* | string | username | 1829 | | password* | string | password | 1830 | 1831 | \* Fields with an asterisk are REQUIRED. 1832 | 1833 | ### Client Certificate Credentials Object 1834 | 1835 | | Field | Type | Description | 1836 | | ----- | ---- | ----------- | 1837 | | client_certificate* | string | the PEM encoded certificate | 1838 | | client_key* | string | the PEM encoded private key | 1839 | 1840 | \* Fields with an asterisk are REQUIRED. 1841 | 1842 | 1843 | 1844 | ## Operation Object 1845 | 1846 | 1847 | Operation objects are meant for clients. They SHOULD NOT convey any Service Manager implementation or process details or use internal terminology. Status description should be meaningful to the majority of end-users. 1848 | Operation objects are created as a result of a REST call to the SM API. 1849 | 1850 | | Field | Type | Description | 1851 | | -------------- | ---- | ----------- | 1852 | | id* | string | The operation ID. | 1853 | | description | string | A user-facing message that can be used to tell the user details about the operation. | 1854 | | type* | string | can be one of CREATE, UPDATE, DELETE | 1855 | | state* | string | Valid values are `in progress`, `succeeded`, and `failed`. While `"state": "in progress"`, the Platform SHOULD continue polling. A response with `"state": "succeeded"` or `"state": "failed"` MUST cause the Platform to cease polling. | 1856 | | resource_id | string | The ID of the resource. It MUST be present for update and delete requests. It MUST also be present when `"state": "succeeded"`. It SHOULD be present for create operation as soon as the ID of new entity is known. | 1857 | | resource_type* | string | The type of the resource (e.g. /v1/service_brokers, /v1/service_instances) | 1858 | | platform_id* | string | The ID of the platform from which the resource that is related to the operation originated. | 1859 | | deletion_scheduled | string | The time when deletion of this resource was scheduled [in ISO 8601 format](#data-formats). | 1860 | | reschedule | bool | Whether the operation has reached a checkpoint and is retryable. | 1861 | | reschedule_timestamp | string | The time when reschedule of this resource was scheduled [in ISO 8601 format](#data-formats). | 1862 | | correlation_id | string | The correlation_id from the request related to this operation | 1863 | | labels | collection of [labels](#labels-object) | Additional data associated with the resource entity. MAY be an empty array. | 1864 | | created_at* | string | The time of operation start [in ISO 8601 format](#data-formats). | 1865 | | updated_at* | string | The time of operation end [in ISO 8601 format](#data-formats). This field SHOULD be present if `"state": "succeeded"` or `"state": "failed"`. | 1866 | | errors | array of error object | [Errors](#errors) describing why the operation has failed. | 1867 | | transitive_resources | array of objects | Describes details about transitive resources that are related to the main resource (specified by `resource_id`) and that were also affected by the operation. | 1868 | | ready* | boolean | Whether the resource is ready or not. | 1869 | 1870 | \* Fields with an asterisk are REQUIRED. 1871 | 1872 | ```json 1873 | { 1874 | "id": "203ec548-f7e8-4405-8253-fcc8d3411353", 1875 | "description": "create platform...", 1876 | "type": "create", 1877 | "state": "succeeded", 1878 | "resource_id": "7825db3c-4fd3-4c04-805f-cf791c3fe2da", 1879 | "resource_type": "/v1/platforms", 1880 | "platform_id": "2425db3c-4fd3-4c04-805f-cf791c3fe2cb", 1881 | "deletion_scheduled": "0001-01-01T00:00:00Z", 1882 | "reschedule": false, 1883 | "reschedule_timestamp": "0001-01-01T00:00:00Z", 1884 | "correlation_id": "02b3af2e-7bb1-42f5-a998-725b9b9eca90", 1885 | "labels": { 1886 | "account": [ 1887 | "account-id" 1888 | ] 1889 | }, 1890 | "created_at": "2020-04-27T11:17:58.725628Z", 1891 | "updated_at": "2020-04-27T11:17:58.90543Z", 1892 | "ready": true, 1893 | "transitive_resources": [ 1894 | { 1895 | "id": "d4cbf5da-661c-44f6-a9d3-306c04c59add", 1896 | "operation_type": "create", 1897 | "type": "/v1/visibilities" 1898 | }, 1899 | { 1900 | "id": "910fc7d5-91ce-4190-b722-0523a02c31c5", 1901 | "operation_type": "create", 1902 | "type": "/v1/visibilities" 1903 | }, 1904 | { 1905 | "id": "4ab5f93d-c2bf-472e-abcb-ae798062f6d5", 1906 | "operation_type": "create", 1907 | "type": "/v1/visibilities" 1908 | }, 1909 | { 1910 | "id": "d4cbf5da-661c-44f6-a9d3-306c04c59add", 1911 | "operation_type": "update", 1912 | "type": "/v1/visibilities" 1913 | }, 1914 | { 1915 | "id": "de140874-694a-4579-83ed-139ab3a610b9", 1916 | "operation_type": "create", 1917 | "type": "/v1/notifications" 1918 | }, 1919 | { 1920 | "id": "910fc7d5-91ce-4190-b722-0523a02c31c5", 1921 | "operation_type": "update", 1922 | "type": "/v1/visibilities" 1923 | }, 1924 | { 1925 | "id": "cb9fc3fc-479b-4060-99b9-15a72cb3ffa6", 1926 | "operation_type": "create", 1927 | "type": "/v1/notifications" 1928 | }, 1929 | { 1930 | "id": "4ab5f93d-c2bf-472e-abcb-ae798062f6d5", 1931 | "operation_type": "update", 1932 | "type": "/v1/visibilities" 1933 | }, 1934 | { 1935 | "id": "e591ff90-6352-4e7d-b6c6-4434452e2800", 1936 | "operation_type": "create", 1937 | "type": "/v1/notifications" 1938 | } 1939 | ] 1940 | } 1941 | ``` 1942 | 1943 | ## Labels Object 1944 | 1945 | A label is a key-value pair that can be attached to a resource. The key MUST be a string. The value MUST be a non-empty array of unique strings. Label keys and values MUST be compared in a case-sensitive way. Service Manager resources MAY have any number of labels represented by the `labels` field. The set of labels is not ordered in any way. 1946 | 1947 | This allows querying (filtering) on the `List` API of the resource based on multiple labels. The Service Manager MAY 1948 | attach additional labels to the resources and MAY restrict updates and deletes for some of the labels. 1949 | 1950 | The `labels` MUST be returned as part of the `List` and `Fetch` APIs. 1951 | 1952 | Example of a Resource Entity that has labels: 1953 | 1954 | ```json 1955 | { 1956 | "id": "0941-12c4b6f2-335a-44a3-b971-424ec78c7353", 1957 | ... 1958 | "labels": { 1959 | "label1Key": [ 1960 | "label1Value" 1961 | ], 1962 | "label2Key": [ 1963 | "label2Value1", 1964 | "label2Value2" 1965 | ] 1966 | } 1967 | } 1968 | ``` 1969 | 1970 | ### Label Keys and Values 1971 | 1972 | Label keys SHOULD only consist of alphanumeric characters, periods, hyphens, underscores and MUST NOT contain any white spaces, equals characters ('`=`'), or commas ('`,`'). 1973 | Labels keys SHOULD NOT be longer than 100 characters. The Service Manager MAY reject labels with longer names. 1974 | 1975 | Label values MUST NOT be empty strings or contain newline characters. 1976 | Label values SHOULD NOT be longer than 255 characters. The Service Manager MAY reject labels with longer values. 1977 | 1978 | ### Patching Labels 1979 | 1980 | The PATCH APIs of the resources that support labels MUST support update of labels and label values. 1981 | 1982 | `labels` is an optional field in the request JSON. If present, it MUST be an array of objects. Each object defines a label operation using the following format: 1983 | 1984 | | Field | Type | Description | 1985 | | ----- | ---- | ----------- | 1986 | | op* | string | The label operation to apply. | 1987 | | key* | string | The label key. | 1988 | | values | string array | The label values. If present, MUST NOT be empty. REQUIRED for `add` and `set` operations. | 1989 | 1990 | \* Fields with an asterisk are REQUIRED. 1991 | 1992 | | Operation | Description | 1993 | | --------- | ----------- | 1994 | | add | Adds a new label or new values. If a label with the given `key` does not exist already, it MUST be created with the given `values`. Otherwise, any new values MUST be added to the label. If any of the `values` already exist in the label, they MUST be ignored silently. Any existing values MUST remain unchanged. `values` field is REQUIRED. | 1995 | | remove | Removes a label or some of its values. If a label with the given `key` does not exist, the operation MUST be ignored silently. Otherwise, the given `values` MUST be removed from the specified label. Any existing label values not specified in `values`, MUST remain unchanged. If any of the `values` are not present in the label, they MUST be ignored silently. If the label remains with no values, it MUST be removed completely. If `values` field is not provided, the whole label with all its values MUST be removed. | 1996 | 1997 | All operations in one request MUST be performed as one atomic change. Either all or none of them are performed. 1998 | 1999 | #### Example 2000 | 2001 | ##### Route 2002 | 2003 | `PATCH /v1/:resource_type/:resource_entity_id` 2004 | 2005 | `:resource_type` MUST be a valid Service Manager [resource type](#resource-types). 2006 | 2007 | `:resource_entity_id` MUST be the ID of a previously created resource entity of this resource type. 2008 | 2009 | ##### Request Body 2010 | 2011 | ```json 2012 | ... 2013 | "labels": [ 2014 | { "op": "add", "key": "label1", "values": ["test1", "test2"] }, 2015 | { "op": "remove", "key": "label3" } 2016 | ] 2017 | ... 2018 | ``` 2019 | 2020 | ## Errors 2021 | 2022 | Errors are meant for clients. They SHOULD NOT convey any Service Manager implementation details such as stack traces or use internal terminology. If debug or developer data is required, that data SHOULD be logged and SHOULD be linked via the `reference_id` with this error. 2023 | 2024 | When a request to the Service Manager fails, it MUST return an appropriate HTTP response code. Where the specification defines the expected response code, that response code MUST be used. 2025 | 2026 | The response body MUST be a valid JSON Object. 2027 | For error responses, the following fields are defined. The Service Manager MAY include additional fields within the response. 2028 | 2029 | 2030 | | Response Field | Type | Description | 2031 | | --- | --- | --- | 2032 | | error* | string | A single word that uniquely identifies the error cause. If present, MUST be a non-empty string with no white space. It MAY be used to identify the error programmatically on the client side. See also the [Error Codes](#error-codes) section. | 2033 | | description | string | A user-facing error message explaining why the request failed. If present, MUST be a non-empty string. | 2034 | 2035 | \* Fields with an asterisk are REQUIRED. 2036 | 2037 | Example: 2038 | 2039 | ```json 2040 | { 2041 | "error": "Unauthorized", 2042 | "description": "The supplied credentials could not be authorized." 2043 | } 2044 | ``` 2045 | 2046 | ### Error Codes 2047 | 2048 | There are failure scenarios described throughout this specification for which 2049 | the `error` field MUST contain a specific string. Service Broker authors MUST 2050 | use these error codes for the specified failure scenarios. 2051 | 2052 | | Error | Status Code | Reason | Expected Action | 2053 | | --- | --- | --- | --- | 2054 | | BrokerError | xxx | The upstream broker returned an error. | | 2055 | | BadRequest | 400 | Malformed or missing mandatory data. This error SHOULD only be used if there is no other, more specific defined error. | Retry with corrected input data. | 2056 | | InvalidLabelQuery | 400 | The label query is invalid. | Retry with corrected label query. | 2057 | | InvalidFieldQuery | 400 | The field query is invalid. | Retry with corrected field query. | 2058 | | Unauthorized | 401 | Unauthenticated request. | Provide credentials or a token. | 2059 | | Forbidden | 403 | The current user has no permission to execute the operation. | Retry operation with a different user. | 2060 | | NotFound | 404 | Entity not found or not visible to the current user. | | 2061 | | Conflict | 409 | An entity with this name already exists. | Retry creation with another name. | 2062 | | VisibilityAlreadyExists | 409 | A visibility for this Platform and Service Plan combination already exists. | Update visibility instead. | 2063 | | Gone | 410 | There is no data about the operation anymore. | Don't retry. | 2064 | | ConcurrentOperation | 422 | The entity is already processed by another operation. | Retry after the currently running operation is finished. | 2065 | 2066 | ## Mitigating Orphans 2067 | 2068 | Service Manager MUST also handle the orphan mitigation process as described in the [Orphan Mitigation section](https://github.com/openservicebrokerapi/servicebroker/blob/master/spec.md#orphan-mitigation) of the OSB spec for Service Instances and Binding that have been created by the Service Manager. How this is done is an implementation detail. 2069 | 2070 | The Service Manager MAY create an operation when the orphan mitigation is in process (deletion of the Service Instance or Binding is running). This allows users to track the progress and potentially failed attempts. 2071 | -------------------------------------------------------------------------------- /release-notes.md: -------------------------------------------------------------------------------- 1 | # Service Manager Specification Release Notes 2 | 3 | 4 | ## init 5 | 2018-02-28 6 | 7 | * Repository is created 8 | 9 | -------------------------------------------------------------------------------- /scripts/check.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # Copyright 2018 4 | # 5 | # Licensed under the Apache License, Version 2.0 (the "License"); 6 | # you may not use this file except in compliance with the License. 7 | # You may obtain a copy of the License at 8 | # 9 | # http://www.apache.org/licenses/LICENSE-2.0 10 | # 11 | # Unless required by applicable law or agreed to in writing, software 12 | # distributed under the License is distributed on an "AS IS" BASIS, 13 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 | # See the License for the specific language governing permissions and 15 | # limitations under the License. 16 | # 17 | # This script will excute static ckecks on *.md and *.html files 18 | # 19 | # Usage: check.sh 20 | 21 | set -o errexit 22 | set -o nounset 23 | set -o pipefail 24 | 25 | # Static check functions 26 | 27 | # Function that checks if file is empty 28 | function checkIfFileIsEmpty { 29 | if [ ! -s $1 ] 30 | then 31 | echo [ERROR] Empty file: $1 32 | exit 1 33 | fi 34 | } 35 | 36 | # Locating files in the repository 37 | REPODIR=$(dirname "${BASH_SOURCE}")/.. 38 | FULL_PATH=$( cd $REPODIR && pwd) 39 | Files=$(find -L $FULL_PATH -type f -name "*.md" -o -name "*.htm*" | sort) 40 | 41 | # Main loop over all files 42 | for file in ${Files}; do 43 | echo [CHECKS] $file 44 | 45 | checkIfFileIsEmpty $file 46 | 47 | echo [VALID] $file 48 | 49 | done 50 | --------------------------------------------------------------------------------