The WSO2 API Manager Service Catalog API manages service discovery and cataloging. It enables developers to register their backend services in a RESTful manner and supports the API-first integration approach in WSO2 API Manager.
# Copyright (c) 2020, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#---------------------------------------------------------------------------
openapi: "3.0.0"
info:
title: Service Catalog APIs
description: |
This specifies a **RESTful API** for Service Catalog.
# Authentication
Our REST APIs are protected using OAuth2 and access control is achieved through scopes. Before you start invoking
the the API you need to obtain an access token with the required scopes. This guide will walk you through the steps
that you will need to follow to obtain an access token.
First you need to obtain the consumer key/secret key pair by calling the dynamic client registration (DCR) endpoint. You can add your preferred grant types
in the payload. A Sample payload is shown below.
```
{
"callbackUrl":"www.google.lk",
"clientName":"rest_api_service_catalog",
"owner":"admin",
"grantType":"client_credentials password refresh_token",
"saasApp":true
}
```
Create a file (payload.json) with the above sample payload, and use the cURL shown bellow to invoke the DCR endpoint. Authorization header of this should contain the
base64 encoded admin username and password.
**Format of the request**
```
curl -X POST -H "Authorization: Basic Base64(admin_username:admin_password)" -H "Content-Type: application/json"
\ -d @payload.json https://<host>:<servlet_port>/client-registration/v0.17/register
```
**Sample request**
```
curl -X POST -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json"
\ -d @payload.json https://localhost:9443/client-registration/v0.17/register
```
Following is a sample response after invoking the above curl.
```
{
"clientId": "fOCi4vNJ59PpHucC2CAYfYuADdMa",
"clientName": "rest_api_service_catalog",
"callBackURL": "www.google.lk",
"clientSecret": "a4FwHlq0iCIKVs2MPIIDnepZnYMa",
"isSaasApplication": true,
"appOwner": "admin",
"jsonString": "{\"grant_types\":\"client_credentials password refresh_token\",\"redirect_uris\":\"www.google.lk\",\"client_name\":\"rest_api123\"}",
"jsonAppAttribute": "{}",
"tokenType": null
}
```
Next you must use the above client id and secret to obtain the access token.
We will be using the password grant type for this, you can use any grant type you desire.
You also need to add the proper **scope** when getting the access token. All possible scopes for Service Catalog REST API can be viewed in **OAuth2 Security** section
of this document and scope for each resource is given in **authorization** section of resource documentation.
Following is the format of the request if you are using the password grant type.
```
curl -k -d "grant_type=password&username=<admin_username>&password=<admin_passowrd>&scope=<scopes seperated by space>"
\ -H "Authorization: Basic base64(cliet_id:client_secret)"
\ https://<host>:<servlet_port>/oauth2/token
```
**Sample request**
```
curl https://localhost:9443/oauth2/token -k \
-H "Authorization: Basic Zk9DaTR2Tko1OVBwSHVjQzJDQVlmWXVBRGRNYTphNEZ3SGxxMGlDSUtWczJNUElJRG5lcFpuWU1h" \
-d "grant_type=password&username=admin&password=admin&scope=service_catalog:service_view service_catalog:service_write"
```
Shown below is a sample response to the above request.
```
{
"access_token": "e79bda48-3406-3178-acce-f6e4dbdcbb12",
"refresh_token": "a757795d-e69f-38b8-bd85-9aded677a97c",
"scope": "service_catalog:service_view service_catalog:service_write",
"token_type": "Bearer",
"expires_in": 3600
}
```
Now you have a valid access token, which you can use to invoke an API.
Navigate through the API descriptions to find the required API, obtain an access token as described above and invoke the API with the authentication header.
If you use a different authentication mechanism, this process may change.
version: '1.2'
servers:
- url: 'https://apis.wso2.com/api/service-catalog/v1'
- url: 'http://apis.wso2.com/api/service-catalog/v1'
paths:
######################################################
# The Service Catalog API operations
######################################################
/services:
#-----------------------------------------------------
# Retrieve/search services in the service catalog
#-----------------------------------------------------
get:
summary: Retrieve/search services
description: |
Retrieve or search services in the service catalog of the user's organization or tenant. Search is supported
using the name, version, definitionType and key of the service.
Search based on the definition type and key of the service will always be an exact search. If you want to
execute an exact search for either name or version the parameter should be given inside double quotation.
operationId: searchServices
security:
- OAuth2Security:
- service_catalog:service_view
- apim:api_view
tags:
- Services
parameters:
- name: name
in: query
description: |
Filter services by the name of the service
schema:
type: string
- name: version
in: query
description: |
Filter services by version of the service
schema:
type: string
- name: definitionType
in: query
description: |
Filter services by definitionType
schema:
type: string
enum:
- OAS
- WSDL1
- WSDL2
- GRAPHQL_SDL
- ASYNC_API
- name: key
in: query
description: |
Comma seperated keys of the services to check
schema:
type: string
- name: shrink
in: query
description: |
If this set to true, a minimal set of fields will be provided for each service including the md5
schema:
type: boolean
default: false
- $ref: '#/components/parameters/sortBy'
- $ref: '#/components/parameters/sortOrder'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
200:
description: |
Paginated matched list of services returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceList'
400:
$ref: '#/components/responses/BadRequest'
401:
$ref: '#/components/responses/Unauthorized'
500:
$ref: '#/components/responses/InternalServerError'
x-code-samples:
- lang: Curl
label: Exact search by name
source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
"https://127.0.0.1:9443/api/am/service-catalog/v1/services?name=%22Pet%20Service%22"'
- lang: Curl
label: Matching search by name
source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
"https://127.0.0.1:9443/api/am/service-catalog/v1/services?name=Pet%20Service"'
- lang: Curl
label: Exact search by version
source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
"https://127.0.0.1:9443/api/am/service-catalog/v1/services?version=%221.0.0%22"'
- lang: Curl
label: Matching search by version
source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
"https://127.0.0.1:9443/api/am/service-catalog/v1/services?version=1.0.0"'
- lang: Curl
label: Get all versions of a service
source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
"https://127.0.0.1:9443/api/am/service-catalog/v1/services?name=%22Pet%20Service%22"'
#-----------------------------------------------------
# Adds new service to the service catalog
#-----------------------------------------------------
post:
summary: Add a new service to Service Catalog
description: |
Add a new service to the service catalog of the user's organization (or tenant)
by specifying the details of the service along with its definition.
security:
- OAuth2Security:
- service_catalog:service_write
tags:
- Services
operationId: addService
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/ServiceSchema'
responses:
201:
description: |
Created.
Successful response with the newly created service as the response payload
content:
application/json:
schema:
$ref: '#/components/schemas/Service'
400:
$ref: '#/components/responses/BadRequest'
401:
$ref: '#/components/responses/Unauthorized'
415:
$ref: '#/components/responses/UnsupportedMediaType'
500:
$ref: '#/components/responses/InternalServerError'
x-code-samples:
- lang: Curl
source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
-F "[email protected]" -F "[email protected];type=application/json" "https://127.0.0.1:9443/api/am/service-catalog/v1/services"'
/services/{serviceId}:
#-----------------------------------------------------
# Retrieve a specific service in the service catalog
#-----------------------------------------------------
get:
summary: Get details of a service
description: |
Get details of a service using the id of the service.
security:
- OAuth2Security:
- service_catalog:service_view
- apim:api_view
operationId: getServiceById
tags:
- Services
parameters:
- $ref: '#/components/parameters/serviceId'
responses:
200:
description: |
Requested service in the service catalog is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/Service'
400:
$ref: '#/components/responses/BadRequest'
401:
$ref: '#/components/responses/Unauthorized'
404:
$ref: '#/components/responses/NotFound'
500:
$ref: '#/components/responses/InternalServerError'
x-code-samples:
- lang: Curl
source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
"https://127.0.0.1:9443/api/am/service-catalog/v1/services"'
#-----------------------------------------------------
# Update a service in the service catalog
#-----------------------------------------------------
put:
summary: Update a service
description: |
Update a service's details and definition
security:
- OAuth2Security:
- service_catalog:service_write
operationId: updateService
tags:
- Services
parameters:
- $ref: '#/components/parameters/serviceId'
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/ServiceSchema'
responses:
200:
description: |
Updated.
Successful response with the newly updated service as entity in the body.
content:
application/json:
schema:
$ref: '#/components/schemas/Service'
400:
$ref: '#/components/responses/BadRequest'
401:
$ref: '#/components/responses/Unauthorized'
404:
$ref: '#/components/responses/NotFound'
500:
$ref: '#/components/responses/InternalServerError'
x-code-samples:
- lang: Curl
source: 'curl -k -X PUT -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
-F "[email protected]" -F "[email protected];type=application/json"
"https://127.0.0.1:9443/api/am/service-catalog/v1/services/7b3d976a-620a-4435-9649-e806f30dc7cf"'
#-----------------------------------------------------
# Delete a service in the service catalog
#-----------------------------------------------------
delete:
summary: Delete a service
description: |
Delete a service by providing the service id
security:
- OAuth2Security:
- service_catalog:service_write
operationId: deleteService
tags:
- Services
parameters:
- $ref: '#/components/parameters/serviceId'
responses:
204:
description: |
Successfully deleted the catalog entry.
400:
$ref: '#/components/responses/BadRequest'
401:
$ref: '#/components/responses/Unauthorized'
404:
$ref: '#/components/responses/NotFound'
409:
$ref: '#/components/responses/Conflict'
500:
$ref: '#/components/responses/InternalServerError'
x-code-samples:
- lang: Curl
source: 'curl -k -X DELETE -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
"https://127.0.0.1:9443/api/am/service-catalog/v1/services/32b4541f-ce7e-47a6-9c0c-c3db18128c50"'
#-----------------------------------------------------
# Retrieve definition of a service in the service catalog
#-----------------------------------------------------
/services/{serviceId}/definition:
get:
summary: Retrieve a service definition
description: |
Retrieve the definition of a service identified by the service id.
security:
- OAuth2Security:
- service_catalog:service_view
- apim:api_view
operationId: getServiceDefinition
tags:
- Services
parameters:
- $ref: '#/components/parameters/serviceId'
responses:
200:
description: |
Successful response with the definition file as entity in the body.
content:
application/json:
schema:
type: string
application/yaml:
schema:
type: string
format: binary
400:
$ref: '#/components/responses/BadRequest'
401:
$ref: '#/components/responses/Unauthorized'
404:
$ref: '#/components/responses/NotFound'
500:
$ref: '#/components/responses/InternalServerError'
x-code-samples:
- lang: Curl
source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
"https://127.0.0.1:9443/api/am/service-catalog/v1/services/3784c2da-2f2a-4af9-8a43-ef207fb4d739/definition"'
#-------------------------------------------------------------------
# Retrieve the information of APIs that use a given service
#-------------------------------------------------------------------
/services/{serviceId}/usage:
get:
summary: Retrieve the API Info that use the given service
description: |
Retrieve the id, name, context and version of the APIs that used by the service
security:
- OAuth2Security:
- service_catalog:service_view
- apim:api_view
operationId: getServiceUsage
tags:
- Services
parameters:
- $ref: '#/components/parameters/serviceId'
responses:
200:
description: |
List of APIs that uses the service in the service catalog is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/APIList'
400:
$ref: '#/components/responses/BadRequest'
401:
$ref: '#/components/responses/Unauthorized'
404:
$ref: '#/components/responses/NotFound'
500:
$ref: '#/components/responses/InternalServerError'
x-code-samples:
- lang: Curl
source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
"https://127.0.0.1:9443/api/am/service-catalog/v1/services/3784c2da-2f2a-4af9-8a43-ef207fb4d739/usage"'
#-------------------------------------------------------------------
# Import a service into the service catalog from a zipped archive
#-------------------------------------------------------------------
/services/import:
post:
summary: Import a service
description: |
Import a service by providing an archived service
security:
- OAuth2Security:
- service_catalog:service_write
operationId: importService
tags:
- Services
parameters:
- name: overwrite
in: query
description: |
Whether to overwrite if there is any existing service with the same name and version.
required: false
schema:
type: boolean
default: false
requestBody:
required: false
content:
multipart/form-data:
schema:
required:
- file
properties:
file:
type: string
description: |
Zip archive consisting of exported Application Configuration.
format: binary
verifier:
type: string
responses:
200:
description: |
Successful response with the imported service metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceInfoList'
headers:
ETag:
$ref: '#/components/headers/ETag'
400:
$ref: '#/components/responses/BadRequest'
401:
$ref: '#/components/responses/Unauthorized'
500:
$ref: '#/components/responses/InternalServerError'
x-code-samples:
- lang: Curl
source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
-F "[email protected]" "https://127.0.0.1:9443/api/am/service-catalog/v1/services/import?overwrite=true"'
#----------------------------------------------------------
# Exporting a service as a zipped archive
#----------------------------------------------------------
/services/export:
#-----------------------------------------
# Retrieve a service as a zipped archive
#-----------------------------------------
get:
summary: Export a service
description: |
Export a service as an archived zip file.
security:
- OAuth2Security:
- service_catalog:service_view
operationId: exportService
tags:
- Services
parameters:
- name: name
in: query
description: |
Name of the service to export
required: true
schema:
type: string
- name: version
in: query
description: |
Version of the service to export
required: true
schema:
type: string
responses:
200:
description: |
Successful response as the exported service as a zipped archive.
content:
application/zip:
schema:
type: string
format: binary
headers:
ETag:
$ref: '#/components/headers/ETag'
401:
$ref: '#/components/responses/Unauthorized'
404:
$ref: '#/components/responses/NotFound'
500:
$ref: '#/components/responses/InternalServerError'
x-code-samples:
- lang: Curl
source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
"https://127.0.0.1:9443/api/am/service-catalog/v1/services/export?name=Single1Curl&version=1.0.0" > services.zip'
######################################################
# The Service Catalog API settings
######################################################
/settings:
#-----------------------------------------------------
# Retrieve Service Catalog settings
#-----------------------------------------------------
get:
summary: Retrieve service catalog API settings
description: |
Retrieve Service Catalog API settings
operationId: getSettings
tags:
- Settings
responses:
200:
description: |
OK.
Settings returned
content:
application/json:
schema:
$ref: '#/components/schemas/Settings'
401:
$ref: '#/components/responses/Unauthorized'
404:
$ref: '#/components/responses/NotFound'
500:
$ref: '#/components/responses/InternalServerError'
x-code-samples:
- lang: Curl
source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
"https://127.0.0.1:9443/api/am/service-catalog/v1/settings"'
components:
#-------------------------------------------------------
# The security schemes of resources used by some of the APIs
#-------------------------------------------------------
securitySchemes:
OAuth2Security:
type: oauth2
flows:
password:
tokenUrl: https://localhost:9443/oauth2/token
scopes:
service_catalog:service_view: view access to services in service catalog
service_catalog:service_write: write access to services in service catalog
apim:api_view: view access to services for read only users
#-------------------------------------------------------
# The definitions of resources used by some of the APIs
#-------------------------------------------------------
schemas:
ServiceInfoList:
title: Services List
type: object
properties:
count:
type: integer
description: |
MD5 hashes of services returned.
example: 1
list:
type: array
items:
$ref: '#/components/schemas/ServiceInfo'
ServiceListExpanded:
title: Services List
type: object
properties:
count:
type: integer
description: |
MD5 hashes of services returned.
example: 1
list:
type: array
items:
$ref: '#/components/schemas/Service'
pagination:
$ref: '#/components/schemas/Pagination'
APIList:
title: API List
type: object
properties:
count:
type: integer
description: |
Number of APIs returned.
example: 1
list:
type: array
items:
$ref: '#/components/schemas/APIInfo'
APIInfo:
title: API Info object with basic API details.
type: object
properties:
id:
type: string
example: 01234567-0123-0123-0123-012345678901
name:
type: string
example: CalculatorAPI
displayName:
type: string
example: Calculator API
description: |
Display name of the API.
This is the name that will be displayed in the Publisher and DevPortal.
If not provided, the name will be used as the display name.
context:
type: string
example: CalculatorAPI
version:
type: string
example: 1.0.0
provider:
type: string
example: admin
#-----------------------------------------------------
# The Service Catalog Entry resource
#-----------------------------------------------------
Verifier:
type: object
title: Json array of md5 hash values of Service Catalog Entry objects
required:
- key
- md5
properties:
key:
type: string
pattern: '^[^\*]+$'
example: petStore-1.0.0
md5:
type: string
example: e27ef979af14c72783b8112dc41c3434c09763ddb230e1a829d5f9134d1abd07
#-----------------------------------------------------
# The Paginated Service Entry Array resource
#-----------------------------------------------------
ServiceList:
type: object
title: Paginated List of Services in Service Catalog
properties:
list:
type: array
title: List of Services in Service Catalog
items:
$ref: '#/components/schemas/Service'
pagination:
$ref: '#/components/schemas/Pagination'
#-----------------------------------------------------
# The Service resource model
#-----------------------------------------------------
Service:
type: object
title: The Service Object
required:
- name
- version
- definitionType
- serviceUrl
properties:
id:
type: string
example: 01234567-0123-0123-0123-012345678901
readOnly: true
name:
type: string
pattern: '^[^\*]+$'
example: Pizzashack-Endpoint
maxLength: 255
minLength: 1
description:
type: string
example: A Catalog Entry that exposes a REST endpoint
maxLength: 1024
version:
type: string
example: v1
maxLength: 30
minLength: 1
serviceKey:
type: string
example: Pizzashack-Endpoint-1.0.0
maxLength: 512
serviceUrl:
type: string
example: http://localhost/pizzashack
definitionType:
type: string
description: The type of the provided API definition
example: OAS3
enum:
- OAS2
- OAS3
- WSDL1
- WSDL2
- GRAPHQL_SDL
- ASYNC_API
securityType:
type: string
description: The security type of the endpoint
example: BASIC
enum:
- BASIC
- DIGEST
- OAUTH2
- X509
- API_KEY
- NONE
default: NONE
mutualSSLEnabled:
type: boolean
description: Whether Mutual SSL is enabled for the endpoint
default: false
example: false
usage:
type: integer
description: Number of usages of the service in APIs
readOnly: true
example: 1
createdTime:
type: string
readOnly: true
example: '2020-02-20T13:57:16.229'
lastUpdatedTime:
type: string
readOnly: true
example: '2020-02-20T13:57:16.229'
md5:
type: string
example: 36583a6a249b410e7fc4f892029709cac09763ddb230e1a829d5f9134d1abd07
definitionUrl:
type: string
example: https://petstore.swagger.io/v2/swagger.json
ServiceInfo:
type: object
title: The Service Info object
properties:
id:
type: string
example: 01234567-0123-0123-0123-012345678901
readOnly: true
name:
type: string
pattern: '^[^\*]+$'
example: PizzashackEndpoint
key:
type: string
example: PizzashackEndpoint-1.0.0
version:
type: string
example: v1
md5:
type: string
example: 36583a6a249b410e7fc4f892029709cac09763ddb230e1a829d5f9134d1abd07
#-----------------------------------------------------
# The Service Schema resource
#-----------------------------------------------------
ServiceSchema:
type: object
title: The Service Schema object
required:
- serviceMetadata
properties:
serviceMetadata:
$ref: '#/components/schemas/Service'
definitionFile:
type: string
format: binary
inlineContent:
type: string
description: Inline content of the document
#-----------------------------------------------------
# The settings resource
#-----------------------------------------------------
Settings:
title: SettingsDTO
properties:
scopes:
type: array
items:
type: string
example: service_catalog:service_view
#-----------------------------------------------------
# The Error resource
#-----------------------------------------------------
Error:
type: object
title: Error object returned with 4XX HTTP Status
required:
- code
- message
properties:
code:
type: integer
format: int64
message:
type: string
description: Error message.
description:
type: string
description: |
A detail description about the error message.
moreInfo:
type: string
description: |
Preferably an url with more details about the error.
error:
type: array
description: |
If there are more than one error list them out.
For example, list out validation errors by each field.
items:
$ref: '#/components/schemas/ErrorListItem'
#-----------------------------------------------------
# The Error List Item resource
#-----------------------------------------------------
ErrorListItem:
type: object
title: Description of individual errors that may have occurred during a request.
required:
- code
- message
properties:
code:
type: string
message:
type: string
description: |
Description about individual errors occurred
description:
type: string
description: |
A detail description about the error message.
#-----------------------------------------------------
# The pagination resource
#-----------------------------------------------------
Pagination:
title: Pagination
properties:
offset:
type: integer
example: 0
limit:
type: integer
example: 1
total:
type: integer
example: 10
next:
type: string
description: |
Link to the next subset of resources qualified.
Empty if no more resources are to be returned.
previous:
type: string
description: |
Link to the previous subset of resources qualified.
Empty if current subset is the first subset returned.
responses:
BadRequest:
description: Bad Request. Invalid request or validation error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: Bad Request
description: Invalid request or validation error
moreInfo: ""
error: []
InternalServerError:
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 500
message: Int
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wso2/refs/heads/main/openapi/wso2-service-catalog-api.yaml