Service Registration
Every microservice or API needs to register itself to OAuth2 server in order to control who can access it. During the registration/on-boarding, a list of scopes defined in the OpenAPI specification or other schema contracts for GraphQL and Hybrid RPC should be populated as well. This list of scopes will be used for clients to register scopes in order to access this particular service or API during client registration.
This service has several endpoints and listens to port 6883.
specification.
swagger: '2.0'
info:
version: 1.0.0
title: OAuth2 Service Registration
description: OAuth2 Service Registration microservices endpoints.
contact:
email: [email protected]
license:
name: Apache 2.0
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
host: oauth2.networknt.com
schemes:
- http
- https
consumes:
- application/json
produces:
- application/json
paths:
/oauth2/service:
post:
description: Return a service object
operationId: createService
parameters:
- in: body
name: body
description: Service object that needs to be added
required: true
schema:
$ref: '#/definitions/Service'
responses:
'200':
description: Successful response
schema:
$ref: '#/definitions/Service'
security:
- service_auth:
- oauth.service.w
put:
description: Return the updated service
operationId: updateService
parameters:
- in: body
name: body
description: Service object that needs to be added
required: true
schema:
$ref: '#/definitions/Service'
responses:
'200':
description: Successful response
schema:
$ref: '#/definitions/Service'
security:
- service_auth:
- oauth.service.w
get:
description: Return all services
operationId: getAllService
parameters:
- name: page
in: query
description: Page number
required: true
type: integer
format: int32
- name: pageSize
in: query
description: Pag size
required: false
type: integer
format: int32
- name: serviceId
in: query
description: Partial serviceId for filter
required: false
type: string
responses:
'200':
description: successful operation
schema:
type: array
items:
$ref: '#/definitions/Service'
security:
- service_auth:
- oauth.service.r
'/oauth2/service/{serviceId}':
delete:
description: Delete a service by Id
operationId: deleteService
parameters:
- name: serviceId
in: path
description: Service Id
required: true
type: string
responses:
'400':
description: Invalid serviceId supplied
'404':
description: Service not found
security:
- service_auth:
- oauth.service.w
get:
description: Get a service by Id
operationId: getService
parameters:
- name: serviceId
in: path
description: Service Id
required: true
type: string
responses:
'200':
description: Successful response
schema:
$ref: '#/definitions/Service'
'400':
description: Invalid serviceId supplied
'404':
description: Service not found
security:
- service_auth:
- oauth.service.r
- oauth.service.w
'/oauth2/service/{serviceId}/endpoint':
post:
description: create endpoints for service
operationId: createServiceEndpoint
parameters:
- name: serviceId
in: path
description: Service Id
required: true
type: string
- in: body
name: body
description: A list of endpoint object
required: true
schema:
type: array
items:
$ref: '#/definitions/ServiceEndpoint'
responses:
'201':
description: Successful response
security:
- service_auth:
- oauth.service.w
delete:
description: Delete all endpoints for a service
operationId: deleteServiceEndpoint
parameters:
- name: serviceId
in: path
description: Service Id
required: true
type: string
responses:
'400':
description: Invalid serviceId supplied
'404':
description: Service not found
security:
- service_auth:
- oauth.service.w
get:
description: Get all endpoints for a service
operationId: getServiceEndpoint
parameters:
- name: serviceId
in: path
description: Service Id
required: true
type: string
responses:
'200':
description: Successful response
schema:
type: array
items:
$ref: '#/definitions/ServiceEndpoint'
'400':
description: Invalid serviceId supplied
'404':
description: ServiceEndpoint not found
security:
- service_auth:
- oauth.service.r
- oauth.service.w
securityDefinitions:
service_auth:
type: oauth2
authorizationUrl: 'http://localhost:8888/oauth2/code'
flow: implicit
scopes:
oauth.service.w: write oauth service
oauth.service.r: read oauth service
definitions:
Service:
type: object
required:
- serviceId
- serviceName
- serviceType
- scope
properties:
serviceId:
type: string
description: a unique service id
serviceType:
type: string
description: service type
enum:
- swagger
- openapi
- graphql
- hybrid
serviceName:
type: string
description: service name
serviceDesc:
type: string
description: service description
ownerId:
type: string
description: service owner userId
scope:
type: string
description: service scopes separated by space
createDt:
type: string
format: date-time
description: create date time
updateDt:
type: string
format: date-time
description: update date time
ServiceEndpoint:
type: object
required:
- endpoint
- operation
- scope
properties:
endpoint:
type: string
description: a combination of path and method to uniquely identify an operation
operation:
type: string
description: operationId of the endpoint
scope:
type: string
description: scope associated with the endpoint
/oauth2/[email protected]
This endpoint gets all the services from service with filter and sorted on serviceId. A page query parameter is mandatory and pageSize and serviceId filter are optional.
- page
Page number which must be specified. It starts with 1 and an empty list will be returned if the page is greater than the last page.
- pageSize
Default pageSize is 10, and you can overwrite it with another number. Please don’t use a big number due to performance reasons.
- serviceId
This is the only filter available and it supports filters by starting with a few characters. For example, “serviceId=abc” means any serviceId starts with “abc”. The result is also sorted by serviceId in the pagination.
The following validation will be performed in the service.
- If page is missing from the query parameter, an error will be returned.
"ERR11000": {
"statusCode": 400,
"code": "ERR11000",
"message": "VALIDATOR_REQUEST_PARAMETER_QUERY_MISSING",
"description": "Query parameter '%s' is required on path '%s' but not found in request."
}
/oauth2/[email protected]
This endpoint is used to create a new service. The following validation will be performed before a new service is created.
- If serviceId exists in the cache, then the following error will be returned.
"ERR12018": {
"statusCode": 400,
"code": "ERR12018",
"message": "SERVICE_ID_EXISTS",
"description": "Service id %s exists."
}
- If ownerId doesn’t exist in user cache, then the following error will be returned.
"ERR12013": {
"statusCode": 404,
"code": "ERR12013",
"message": "USER_NOT_FOUND",
"description": "User %s is not found."
}
/oauth2/[email protected]
This is the endpoint to update existing services. Before service is updated, the following validation will be performed.
- If serviceId cannot be found in the service cache, then the following error will be returned.
"ERR12015": {
"statusCode": 404,
"code": "ERR12015",
"message": "SERVICE_NOT_FOUND",
"description": "Service %s is not found."
}
- If ownerId doesn’t exist in user cache, then the following error will be returned.
"ERR12013": {
"statusCode": 404,
"code": "ERR12013",
"message": "USER_NOT_FOUND",
"description": "User %s is not found."
}
/oauth2/service/{serviceId}@delete
This endpoint is used to delete existing services. Before the service is deleted, the following validations will be performed.
- If serviceId cannot be found in the service cache, then the following error will be returned.
"ERR12015": {
"statusCode": 404,
"code": "ERR12015",
"message": "SERVICE_NOT_FOUND",
"description": "Service %s is not found."
}
/oauth2/service/{serviceId}@get
This endpoint is used to get a particular service by serviceId. Before the service is returned, the following validation will be performed.
- If serviceId cannot be found in the service cache, then the following error will be returned.
"ERR12015": {
"statusCode": 404,
"code": "ERR12015",
"message": "SERVICE_NOT_FOUND",
"description": "Service %s is not found."
}
/oauth2/service/{serviceId}/[email protected]
This is an endpoint that is used to register endpoints for a particular service. As you can see there is no put method for this resource so all endpoints will be deleted and then insert if this endpoint is called.
Here is an example of request body.
[{"endpoint":"/v1/[email protected]","operation":"createData","scope":"data.w"},{"endpoint":"/v1/[email protected]","operation":"updateData","scope":"data.w"},{"endpoint":"/v1/[email protected]","operation":"retrieveData","scope":"data.r"},{"endpoint":"/v1/[email protected]","operation":"deleteData","scope":"data.w"}]
- If serviceId cannot be found in the service cache, then the following error will be returned.
"ERR12015": {
"statusCode": 404,
"code": "ERR12015",
"message": "SERVICE_NOT_FOUND",
"description": "Service %s is not found."
}
/oauth2/service/{serviceId}/[email protected]
This is an endpoint that is used to delete all the endpoints for a particular service. You have to make sure that there are no client links to the service endpoints before issuing a delete request. Otherwise, you will have database constraint errors.
- If service endpoints cannot be found in the service cache, then the following error will be returned.
"ERR12015": {
"statusCode": 404,
"code": "ERR12042",
"message": "SERVICE_ENDPOINT_NOT_FOUND",
"description": "Service %s is not found."
}
/oauth2/service/{serviceId}/[email protected]
This is an endpoint that is used to get all the endpoints for a particular service.
Here is an example of response body
[{"factoryId":5,"id":5,"operation":"retrieve data","endpoint":"/v1/[email protected]","scope":"data.r"},{"factoryId":5,"id":5,"operation":"create data","endpoint":"/v1/[email protected]","scope":"data.w"}]
- If service endpoints cannot be found in the service cache, then the following error will be returned.
"ERR12015": {
"statusCode": 404,
"code": "ERR12042",
"message": "SERVICE_ENDPOINT_NOT_FOUND",
"description": "Service %s is not found."
}