|
Discover the Microservice Bus
...
msb.address: 10.74.205.123:80
...
API Definition and Swagger-UI
ONAP intends to be a microservices-based architecture and every individual service is exposed as a restful API. Microservice Bus provide mechanisms to collect and display the API description(swagger UI) and metrics of services centrally.
The services should provide the information to Microservice Bus by the below approaches:
...
- REST APIs should be described in a swagger.json file according to Open API Initiative.
- The swagger.json file should be put at the root path of the service url, such as: http(s)://[hostname][:port]/[ServiceType]/[ServiceName]/[Service Version]/Swagger.json
- The swagger.json can be automatically generated by JAVA notation, more information can be find at Swagger Annotations.
For example, the swagger description and UI of the services provided by Microservice Bus:
Service: /api/microservices/v1/
Swagger: /api/microservices/v1/swagger.json
Metrics
- The metrics of service should be published at: http(s)://[hostname][:port]/admin/metrics
- MSB recommend dropwizard metrics for java and PyFormance for Python to generate the metrics data.
For example, the metrics data and UI of the services provided by Microservice Bus:
Metrics data
Image Removed
UI
Image Removed
Register service to the Microservice Bus
| Operation | Register service to the Microservice Bus |
|---|
| URL | /api/microservices/v1/services |
|---|
| Verb | POST |
|---|
| Request |
| Parameter | Mandatory | Parameter type | Data Type | Default | example | Description |
|---|
| Body | Y | Body | JSON String |
| {
"serviceName": " |
|
|---|
catalogv1apicatalog/v1v8",
"protocol": "REST",
"visualRange": "1", |
|
"path":"/aai/v8"
"nodes": [
|
|
{
"ip": "10.74.56.36",
"port": "8988",
"ttl": 0
}
]
}
| Described in the below table | | createOrUpdate | N | Query | boolean | true |
| true: create new instances or replace the old instances if the instance with the same service name, |
|
ipand port exist ipandportexist
false: create new instances and remove all the old instances with the same service name |
| Parameter | Mandatory | Data Type | Default | Description |
|---|
| serviceName | Y | String |
| Service Name, must comply with RFC 1123, only allowsthe ASCII letters 'a' through 'z' , the digits '0' through '9', and the minus sign ('-'). | | version | Y | String |
| Service Version | | url | Y if protocol is 'REST' or 'UI' or 'HTTP' | String |
| the actual URL of the service to be registered | | protocol | Y | String |
| supported protocols: 'REST', 'UI', 'HTTP','TCP' | | visualRange |
|
F| N | String | 1 | Visibility of the service.
External(can be accessed by external systems):0
Internal(can only be accessed by ONAP |
|
consumers| microservices):1 | path | N | String |
| Thecustomizedpublish path of this service. If path parameter is specified when registering the service, the service will be published to apigateway under this path. Otherwise, the service will be published to apigateway using a fixed format: api/{serviceName}/{version}. The customized publish path should only be used for back-compatible. | | enable_ssl | N | boolean | False | True if the registered service is based on https. False if the registered service is based on http. | | nodes | Y | List |
| ip: the |
|
ipof the service ipoftheservice instance node, it could also be a hostname like catalog.onap.org
port: the port of the service instance node
ttl: time to live, this parameter is reserved for later use |
|
| Response | | example | Description |
|---|
{
"serviceName": "catalog",
"version": "v1",
"url": "/api/catalog/v1",
"protocol": "REST",
"visualRange": "1", |
|
|---|
"lb_policy":"ip_hash",
"nodes": [
{
"ip": "10.74.55.66",
"port": "6666",
"ttl": 0 |
|
, "expiration": "2016-02-18T16:19:40+08:00",
"created_at": "2016-02-18T16:03:00+08:00",
"updated_at": "2016-02-18T16:03:00+08:00"
},
{
"ip": "10.74.56.37",
"port": "8989",
"ttl": 0 |
|
,
"expiration": "2016-02-18T16:13:00+08:00",
"created_at": "2016-02-18T16:03:00+08:00", "updated_at": "2016-02-18T16:03:00+08:00"
},
{
"ip": "10.74.56.36",
"port": "8988",
"ttl": 0 |
|
,
"expiration": "2016-02-18T17:04:36+08:00",
"created_at": "2016-02-18T16:03:00+08:00", "updated_at": "2016-02-18T16:03:00+08:00"
, "status": "1"
}
| serviceName: service name
version: version
url: url of the created service instance
protocol: supported protocols: 'REST', 'UI','HTTP','TCP'
nodes: the service instance nodes list to register
lb_policy: Load balancing method, Currently two LB methods are supported, round-robin and ip-hash.
ip: the ip of the service instance node, it could also be a hostname like catalog.onap.org
port: the port of the service instance node
ttl: time to live, this parameter is reserved for later use |
|
status: service status, 1: enabled,0:disabled |
| Success Code | 201 |
|---|
| Error Code |
|---|
415 422 Invalid Parameters
500 Internal Server Error |
Unregister service from the Microservice Bus
| Operation | Unregister service from the Microservice Bus |
|---|
| URL | /api/microservices/v1/services/{serviceName}/version/{version}/nodes/{ip}/{port} |
|---|
| Verb | DELETE |
|---|
| Request | | Parameter | Mandatory | Parameter type | Data Type | Default | example | Description |
|---|
| serviceName | Y | Path | String |
|
| Service Name | | version | N | Path | String |
|
| Service Version | | ip | N | Path | String |
|
| the IP address of the service instance, it could also be a hostname like catalog.onap.org | | port | N | Path | String |
|
| the port of the service instance |
|
|---|
| Response |
|
|---|
| Success Code | 204 |
|---|
| Error Code | 404 Can't find the service instance
|
|---|
415 422 Invalid Parameters
500 Internal Server Error |
Query service from the Microservice Bus
...
if the service did not have version property, you can use the url without version.
/api/[servicename]/
| Operation | Query service from the Microservice Bus |
|---|
| URL | /api/microservices/v1/services/{serviceName}/version/{version} |
|---|
| Verb | GET |
|---|
| Request | | Parameter | Mandatory | Parameter type | Data Type | Default | example | Description |
|---|
| serviceName | N | Path | String |
|
| Service Name | | version | N | Path | String |
|
| Service Version |
|
|---|
| Response | | example | Description |
|---|
{
"serviceName": "catalog",
"version": "v1",
"url": "/api/catalog/v1",
"protocol": "REST",
"visualRange": "1",
"nodes": [
{
"ip": "10.74.55.66",
"port": "6666",
"ttl": 0 |
|
|---|
, "expiration": "2016-02-18T16:19:40+08:00",
"created_at": "2016-02-18T16:03:00+08:00",
"updated_at": "2016-02-18T16:03:00+08:00"
},
{
"ip": "10.74.56.37",
"port": "8989",
"ttl": 0 |
|
, "expiration":"2016-02-18T16:13:00+08:00",
"created_at": "2016-02-18T16:03:00+08:00",
"updated_at": "2016-02-18T16:03:00+08:00"
},
{
"ip": "10.74.56.36",
"port": "8988",
"ttl": 0 |
|
,
"expiration": "2016-02-18T17:04:36+08:00",
"created_at": "2016-02-18T16:03:00+08:00",
"updated_at": "2016-02-18T16:03:00+08:00",
"status": "1"
}
| serviceName: service name
version: version
url: url of the created service instance
protocol: supported protocols: 'REST', 'UI', 'HTTP','TCP'
nodes: the service instance nodes list to register
ip: the ip of the service instance node, it could also be a hostname like catalog.onap.org
port: the port of the service instance node
ttl: time to live, this parameter is reserved for later use |
|
status: service status, 1:eanbled,0:disabled |
| Success Code | 200 |
|---|
| Error Code | 404 Can't find the service instance
|
|---|
415 422 Invalid Parameters
500 Internal Server Error |
...
MSB Client SDK
MSBServiceClient : JAVA SDK for MSB service discovery
RestServiceCreater: JAVA SDK for REST service invocation
MSB Client SDK Example
https://gerrit.onap.org/r/gitweb?p=msb/java-sdk.git;a=tree;f=example;h=1c331f86cbcbdb8cc2935d8ac41169da1a523ec5;hb=refs/heads/master
| Code Block |
|---|
String MSB_IP="127.0.0.1";
int MSB_Port=10081;
MSBServiceClient msbClient = new MSBServiceClient(MSB_IP, MSB_Port);
RestServiceCreater restServiceCreater =
new RestServiceCreater(msbClient);
AnimalServiceClient implProxy =
restServiceCreater.createService(AnimalServiceClient.class);
Animal animal = implProxy.queryAnimal("panda").execute().body();
System.out.println("animal:" + animal); |
Note: In order to test the example application, you need to run MSB following this guide MSB Test Environment Setup
