diff --git a/v2/README.md b/v2/README.md new file mode 100644 index 0000000..fd18d7a --- /dev/null +++ b/v2/README.md @@ -0,0 +1,266 @@ +# Rest API +[![go-doc](https://godoc.org/github.com/redhat-cne/rest-api?status.svg)](https://godoc.org/github.com/redhat-cne/rest-api) +[![Go Report Card](https://goreportcard.com/badge/github.com/redhat-cne/rest-api)](https://goreportcard.com/report/github.com/redhat-cne/rest-api) +[![LICENSE](https://img.shields.io/github/license/redhat-cne/rest-api.svg)](https://github.com/redhat-cne/rest-api/blob/main/LICENSE) + +Available Routes + +```html + +POST /api/ocloudNotifications/v2/subscriptions +GET /api/ocloudNotifications/v2/subscriptions +GET /api/ocloudNotifications/v2/subscriptions/{subscription_id} +DELETE /api/ocloudNotifications/v2/subscriptions/{subscription_id} +GET api/ocloudnotifications/v2/{resource_address}/CurrentState +GET /api/ocloudNotifications/v2/health +GET /api/ocloudNotifications/v2/publishers +DELETE /api/ocloudNotifications/v2/subscriptions +``` + +## Pub/Sub Rest API + +Rest API spec . + +### Version: 1.0.0 + + +### /publishers/ + +#### POST +##### Summary + +Creates a new publisher. + +##### Description + +If publisher creation is success(or if already exists), publisher will be returned with Created (201). + +##### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ---- | +| publisher | body | publisher to add to the list of pub | [PubSub](#pubsub) | + +##### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 201 | publisher/subscription data model | [PubSub](#pubsub) | +| 400 | Error Bad Request | object | + +### /subscriptions/ + +#### POST +##### Summary + +Creates a new subscription. + +##### Description + +If subscription creation is success(or if already exists), subscription will be returned with Created (201). + +##### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ---- | +| subscription | body | subscription to add to the list of subscriptions | yes | [PubSub](#pubsub) | + +##### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 201 | publisher/subscription data model | [PubSub](#pubsub) | +| 400 | Error Bad Request | object | + + + +### /create/event/ + +#### POST +##### Summary + +Creates a new event. + +##### Description + +If publisher is present for the event, then event creation is success and be returned with Accepted (202). + +##### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ---- | +| event | body | event along with publisher id | Yes | [Event](#event) | + +##### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 202 | Accepted | object | +| 400 | Error Bad Request | object | + +### /subscriptions/status/{subscriptionid} + +#### PUT +##### Summary + +Creates a new status ping request. + +##### Description + +If a subscription is present for the request, then status request is success and be returned with Accepted (202). + +##### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ---- | +| subscriptionid | request | subscription id | Yes | | + +##### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 202 | Accepted | object | +| 400 | Error Bad Request | object | + +### Models + +#### Data + +Data ... cloud native events' data Json payload is as follows, +```json + +{ +"version": "v1.0", +"values": [{ +"resource": "/cluster/node/ptp", +"dataType": "notification", +"valueType": "enumeration", +"value": "ACQUIRING-SYNC" +}, { +"resource": "/cluster/node/clock", +"dataType": "metric", +"valueType": "decimal64.3", +"value": 100.3 +}] +} +``` + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| values | [ [DataValue](#datavalue) ] | | Yes | +| version | string | | Yes | + +#### DataType + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| DataType | string | | Yes | + +#### DataValue + +DataValue Json payload is as follows, +```json + +{ +"resource": "/cluster/node/ptp", +"dataType": "notification", +"valueType": "enumeration", +"value": "ACQUIRING-SYNC" +} +``` + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| dataType | [DataType](#datatype) | | yes | +| resource | string | | yes | +| value | object | | yes | +| valueType | [ValueType](#valuetype) | | yes | + +#### Event + +Event Json payload is as follows, +```json + +{ +"id": "5ce55d17-9234-4fee-a589-d0f10cb32b8e", +"type": "event.synchronization-state-chang", +"time": "2021-02-05T17:31:00Z", +"data": { +"version": "v1.0", +"values": [{ +"resource": "/cluster/node/ptp", +"dataType": "notification", +"valueType": "enumeration", +"value": "ACQUIRING-SYNC" +}, { +"resource": "/cluster/node/clock", +"dataType": "metric", +"valueType": "decimal64.3", +"value": 100.3 +}] +} +} +``` +Event request model + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| data | [Data](#data) | | yes | +| dataContentType | string | DataContentType - the Data content type +required | yes | +| dataSchema | [URI](#uri) | | No | +| id | string | ID of the event; must be non-empty and unique within the scope of the producer. +required | yes | +| time | [Timestamp](#timestamp) | | yes | +| type | string | Type - The type of the occurrence which has happened. +required | yes | + +#### PubSub +PubSub Json request payload is as follows, +```json + +{ +"id": "789be75d-7ac3-472e-bbbc-6d62878aad4a", +"endpointUri": "http://localhost:9090/ack/event", +"uriLocation": "}", +"resource": "/east-edge-10/vdu3/o-ran-sync/sync-group/sync-status/sync-state" +} +``` +PubSub request model + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| endpointUri | [URI](#uri) | | yes | +| resource | string | Resource - The type of the Resource. +required | yes | + + +#### Timestamp + +Timestamp wraps time.Time to normalize the time layout to RFC3339. It is +intended to enforce compliance with the Cloud Native events spec for their +definition of Timestamp. Custom marshal methods are implemented to ensure +the outbound Timestamp is a string in the RFC3339 layout. + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| Timestamp | object | Timestamp wraps time.Time to normalize the time layout to RFC3339. It is intended to enforce compliance with the Cloud Native events spec for their definition of Timestamp. Custom marshal methods are implemented to ensure the outbound Timestamp is a string in the RFC3339 layout. | | + +#### URI + +URI is a wrapper to url.URL. It is intended to enforce compliance with +the Cloud Native Events spec for their definition of URI. Custom +marshal methods are implemented to ensure the outbound URI object +is a flat string. + + +#### ValueType + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| ValueType | ENUM | ENUMERATION,DECIMAL | yes | + + +## Collecting metrics with Prometheus +Cloud native events rest API comes with following metrics collectors . +1. Number of events published by the rest api. +2. Number of active subscriptions. +3. Number of active publishers. + +[Metrics details ](docs/metrics.md) diff --git a/v2/server.go b/v2/server.go index fc459be..79fe5ee 100644 --- a/v2/server.go +++ b/v2/server.go @@ -20,9 +20,8 @@ // // Schemes: http, https // Host: localhost:8089 -// basePath: /api/ocloudNotifications/v1 -// Version: 1.0.0 -// Contact: Aneesh Puttur +// BasePath: /api/ocloudNotifications/v2 +// Version: 2.0.0 // // Consumes: // - application/json @@ -265,6 +264,11 @@ func (s *Server) Start() { See note below. 404 Subscription resources are not available (not created). */ + // swagger:route GET /subscriptions + // Get a list of subscription object(s) and their associated properties. + // responses: + // 200: Returns the subscription resources and their associated properties that already exist. + // 400: Bad request by the client. api.HandleFunc("/subscriptions", s.getSubscriptions).Methods(http.MethodGet) //publishers create publisher and send it to a channel that is shared by middleware to process // swagger:operation GET /publishers/ publishers getPublishers diff --git a/v2/swagger.json b/v2/swagger.json index e4337c9..3b5aaad 100644 --- a/v2/swagger.json +++ b/v2/swagger.json @@ -13,14 +13,10 @@ "info": { "description": "Rest API spec .", "title": "Pub/Sub Rest API.", - "contact": { - "name": "Aneesh Puttur", - "email": "aputtur@redhat.com" - }, - "version": "1.0.0" + "version": "2.0.0" }, "host": "localhost:8089", - "basePath": "/api/ocloudNotifications/v1", + "basePath": "/api/ocloudNotifications/v2", "paths": { "/create/event/": { "post": { @@ -147,220 +143,21 @@ } } }, - "definitions": { - "Data": { - "description": "{\n\"version\": \"v1.0\",\n\"values\": [{\n\"resource\": \"/sync/sync-status/sync-state\",\n\"dataType\": \"notification\",\n\"valueType\": \"enumeration\",\n\"value\": \"ACQUIRING-SYNC\"\n}, {\n\"resource\": \"/sync/sync-status/sync-state\",\n\"dataType\": \"metric\",\n\"valueType\": \"decimal64.3\",\n\"value\": 100.3\n}, {\n\"resource\": \"/redfish/v1/Systems\",\n\"dataType\": \"notification\",\n\"valueType\": \"redfish-event\",\n\"value\": {\n\"@odata.context\": \"/redfish/v1/$metadata#Event.Event\",\n\"@odata.type\": \"#Event.v1_3_0.Event\",\n\"Context\": \"any string is valid\",\n\"Events\": [{\"EventId\": \"2162\", \"MemberId\": \"615703\", \"MessageId\": \"TMP0100\"}],\n\"Id\": \"5e004f5a-e3d1-11eb-ae9c-3448edf18a38\",\n\"Name\": \"Event Array\"\n}\n}]\n}", - "type": "object", - "title": "Data ... cloud native events data\nData Json payload is as follows,", - "properties": { - "values": { - "type": "array", - "items": { - "$ref": "#/definitions/DataValue" - }, - "x-go-name": "Values" - }, - "version": { - "type": "string", - "x-go-name": "Version" - } - }, - "x-go-package": "github.com/redhat-cne/sdk-go/pkg/event" - }, - "DataType": { - "type": "string", - "title": "DataType ...", - "x-go-package": "github.com/redhat-cne/sdk-go/pkg/event" - }, - "DataValue": { - "description": "{\n\"resource\": \"/cluster/node/ptp\",\n\"dataType\": \"notification\",\n\"valueType\": \"enumeration\",\n\"value\": \"ACQUIRING-SYNC\"\n}", - "type": "object", - "title": "DataValue ...\nDataValue Json payload is as follows,", - "properties": { - "dataType": { - "$ref": "#/definitions/DataType" - }, - "resource": { - "type": "string", - "x-go-name": "Resource" - }, - "value": { - "x-go-name": "Value" - }, - "valueType": { - "$ref": "#/definitions/ValueType" - } - }, - "x-go-package": "github.com/redhat-cne/sdk-go/pkg/event" - }, - "Event": { - "description": "{\n\"id\": \"5ce55d17-9234-4fee-a589-d0f10cb32b8e\",\n\"type\": \"event.sync.sync-status.synchronization-state-change\",\n\"source\": \"/cluster/node/example.com/ptp/clock_realtime\",\n\"time\": \"2021-02-05T17:31:00Z\",\n\"data\": {\n\"version\": \"v1.0\",\n\"values\": [{\n\"resource\": \"/sync/sync-status/sync-state\",\n\"dataType\": \"notification\",\n\"valueType\": \"enumeration\",\n\"value\": \"ACQUIRING-SYNC\"\n}, {\n\"resource\": \"/sync/sync-status/sync-state\",\n\"dataType\": \"metric\",\n\"valueType\": \"decimal64.3\",\n\"value\": 100.3\n}]\n}\n}\n\nEvent request model", - "type": "object", - "title": "Event represents the canonical representation of a Cloud Native Event.\nEvent Json payload is as follows,", - "properties": { - "data": { - "$ref": "#/definitions/Data" - }, - "dataContentType": { - "description": "DataContentType - the Data content type\n+required", - "type": "string", - "x-go-name": "DataContentType" - }, - "dataSchema": { - "$ref": "#/definitions/URI" - }, - "id": { - "description": "ID of the event; must be non-empty and unique within the scope of the producer.\n+required", - "type": "string", - "x-go-name": "ID" - }, - "source": { - "description": "Source - The source of the occurrence which has happened.\n+required", - "type": "string", - "x-go-name": "Source" - }, - "time": { - "description": "Time - A Timestamp when the event happened.\n+required", - "type": "string", - "x-go-name": "Time" - }, - "type": { - "description": "Type - The type of the occurrence which has happened.\n+required", - "type": "string", - "x-go-name": "Type" - } - }, - "x-go-package": "github.com/redhat-cne/sdk-go/pkg/event" - }, - "PubSub": { - "description": "{\n\"id\": \"789be75d-7ac3-472e-bbbc-6d62878aad4a\",\n\"endpointUri\": \"http://localhost:9090/ack/event\",\n\"uriLocation\": \"http://localhost:8080/api/ocloudNotifications/v1/publishers/{publisherid}\",\n\"resource\": \"/east-edge-10/vdu3/o-ran-sync/sync-group/sync-status/sync-state\"\n}\n\nPubSub request model", - "type": "object", - "title": "PubSub represents the canonical representation of a Cloud Native Event Publisher and Sender .\nPubSub Json request payload is as follows,", - "properties": { - "endpointUri": { - "$ref": "#/definitions/URI" - }, - "id": { - "description": "ID of the pub/sub; is updated on successful creation of publisher/subscription.", - "type": "string", - "x-go-name": "ID" - }, - "resource": { - "description": "Resource - The type of the Resource.\n+required", - "type": "string", - "x-go-name": "Resource" - }, - "uriLocation": { - "$ref": "#/definitions/URI" - } - }, - "x-go-package": "github.com/redhat-cne/sdk-go/pkg/pubsub" - }, - "URI": { - "description": "URI is a wrapper to url.URL. It is intended to enforce compliance with\nthe Cloud Native Events spec for their definition of URI. Custom\nmarshal methods are implemented to ensure the outbound URI object\nis a flat string.", - "type": "object", - "properties": { - "ForceQuery": { - "type": "boolean" - }, - "Fragment": { - "type": "string" - }, - "Host": { - "type": "string" - }, - "OmitHost": { - "type": "boolean" - }, - "Opaque": { - "type": "string" - }, - "Path": { - "type": "string" - }, - "RawFragment": { - "type": "string" - }, - "RawPath": { - "type": "string" - }, - "RawQuery": { - "type": "string" - }, - "Scheme": { - "type": "string" - }, - "User": { - "$ref": "#/definitions/Userinfo" - } - }, - "x-go-package": "github.com/redhat-cne/sdk-go/pkg/types" - }, - "Userinfo": { - "description": "The Userinfo type is an immutable encapsulation of username and\npassword details for a URL. An existing Userinfo value is guaranteed\nto have a username set (potentially empty, as allowed by RFC 2396),\nand optionally a password.", - "type": "object", - "x-go-package": "net/url" - }, - "ValueType": { - "type": "string", - "title": "ValueType ...", - "x-go-package": "github.com/redhat-cne/sdk-go/pkg/event" - } - }, "responses": { "acceptedReq": { - "description": "Accepted", - "schema": { - "type": "object", - "properties": { - "code": { - "description": "HTTP status code 202 - Accepted", - "type": "integer", - "format": "int64", - "x-go-name": "Code" - } - } - } + "description": "Accepted" }, "badReq": { - "description": "Error Bad Request", - "schema": { - "type": "object", - "properties": { - "code": { - "description": "HTTP status code 400 - Bad Request", - "type": "integer", - "format": "int64", - "x-go-name": "Code" - } - } - } + "description": "Error Bad Request" }, "eventResp": { - "description": "PubSub request model", - "schema": { - "$ref": "#/definitions/Event" - } + "description": "PubSub request model" }, "notFoundReq": { - "description": "Error Not Found", - "schema": { - "type": "object", - "properties": { - "code": { - "description": "HTTP status code 404 - Not Found", - "type": "integer", - "format": "int64", - "x-go-name": "Code" - } - } - } + "description": "Error Not Found" }, "pubSubResp": { - "description": "publisher/subscription data model", - "schema": { - "$ref": "#/definitions/PubSub" - } + "description": "publisher/subscription data model" } } } \ No newline at end of file