Skip to content

Latest commit

 

History

History
443 lines (260 loc) · 16.5 KB

README.md

File metadata and controls

443 lines (260 loc) · 16.5 KB

Rest API

go-doc Go Report Card LICENSE

Developers Guide

The REST-API specification below is generated by Swagger tools. Please refer to the Developers Guide on how to use Swagger to generate specs and documentations.

O-RAN Compliant REST API Specification

Starting from release v1.21.0, the REST API implemented in this repo is compliant with O-RAN O-Cloud Notification API Specification for Event Consumers 4.0.

The specification of release v1.0.0 and older can be found here.

Version

2.0.0

All endpoints

events

Method URI Name Summary
GET /api/ocloudNotifications/v2/{ResourceAddress}/CurrentState get current state Pulls the event status notifications for specified ResourceAddress.

health_check

Method URI Name Summary
GET /api/ocloudNotifications/v2/health get health (Extensions to O-RAN API) Returns the health status of API.

publishers

Method URI Name Summary
GET /api/ocloudNotifications/v2/publishers get publishers (Extensions to O-RAN API) Get publishers.

subscriptions

Method URI Name Summary
POST /api/ocloudNotifications/v2/subscriptions create subscription Creates a subscription resource for the Event Consumer.
DELETE /api/ocloudNotifications/v2/subscriptions delete all subscriptions (Extensions to O-RAN API) Delete all subscriptions.
DELETE /api/ocloudNotifications/v2/subscriptions/{subscriptionId} delete subscription Delete a specific subscription.
GET /api/ocloudNotifications/v2/subscriptions/{subscriptionId} get subscription by ID Returns details for a specific subscription.
GET /api/ocloudNotifications/v2/subscriptions get subscriptions Retrieves a list of subscriptions.

Paths

Creates a subscription resource for the Event Consumer. (createSubscription)

POST /api/ocloudNotifications/v2/subscriptions

Creates a new subscription for the required event by passing the appropriate payload.

Parameters

Name Source Type Go type Separator Required Default Description
SubscriptionInfo body SubscriptionInfo models.SubscriptionInfo The payload will include an event notification request, endpointUri and ResourceAddress. The SubscriptionId and UriLocation are ignored in the POST body (these will be sent to the client after the resource is created).

All responses

Code Status Description Has headers Schema
201 Created Shall be returned when the subscription resource is created successfully. schema
400 Bad Request Bad request. For example, the endpoint URI is not correctly formatted. schema
404 Not Found Not Found. Subscription resource is not available. schema
409 Conflict Conflict. The subscription resource already exists. schema

Responses

201 - Shall be returned when the subscription resource is created successfully.

Status: Created

Schema

SubscriptionInfo

400 - Bad request. For example, the endpoint URI is not correctly formatted.

Status: Bad Request

Schema
404 - Not Found. Subscription resource is not available.

Status: Not Found

Schema
409 - Conflict. The subscription resource already exists.

Status: Conflict

Schema

(Extensions to O-RAN API) Delete all subscriptions. (deleteAllSubscriptions)

DELETE /api/ocloudNotifications/v2/subscriptions

Delete all subscriptions.

All responses

Code Status Description Has headers Schema
204 No Content Deleted all subscriptions. schema

Responses

204 - Deleted all subscriptions.

Status: No Content

Schema

Delete a specific subscription. (deleteSubscription)

DELETE /api/ocloudNotifications/v2/subscriptions/{subscriptionId}

Deletes an individual subscription resource object and its associated properties.

Parameters

Name Source Type Go type Separator Required Default Description
subscriptionId path string string ✓ Identifier for subscription resource, created after a successful subscription.

All responses

Code Status Description Has headers Schema
204 No Content Success. schema
404 Not Found Not Found. Subscription resources are not available (not created). schema

Responses

204 - Success.

Status: No Content

Schema
404 - Not Found. Subscription resources are not available (not created).

Status: Not Found

Schema

Pulls the event status notifications for specified ResourceAddress. (getCurrentState)

GET /api/ocloudNotifications/v2/{ResourceAddress}/CurrentState

As a result of successful execution of this method the Event Consumer will receive the current event status notifications of the node that the Event Consumer resides on.

Parameters

Name Source Type Go type Separator Required Default Description
ResourceAddress path string string ✓ Identifier for subscription resource

All responses

Code Status Description Has headers Schema
200 OK Return the pull event status schema
404 Not Found Not Found. Event notification resource is not available on this node. schema

Responses

200 - Return the pull event status

Status: OK

Schema

EventData

404 - Not Found. Event notification resource is not available on this node.

Status: Not Found

Schema

(Extensions to O-RAN API) Returns the health status of API. (getHealth)

GET /api/ocloudNotifications/v2/health

Returns the health status for the ocloudNotifications REST API.

All responses

Code Status Description Has headers Schema
200 OK OK schema

Responses

200 - OK

Status: OK

Schema

(Extensions to O-RAN API) Get publishers. (getPublishers)

GET /api/ocloudNotifications/v2/publishers

Returns a list of publisher details for the cluster node.

All responses

Code Status Description Has headers Schema
200 OK schema
404 Not Found Publishers not found schema

Responses

200

Status: OK

Schema

[]SubscriptionInfo

404 - Publishers not found

Status: Not Found

Schema

Returns details for a specific subscription. (getSubscriptionByID)

GET /api/ocloudNotifications/v2/subscriptions/{subscriptionId}

Returns details for the subscription with ID subscriptionId.

Parameters

Name Source Type Go type Separator Required Default Description
subscriptionId path string string ✓ Identifier for subscription resource, created after a successful subscription.

All responses

Code Status Description Has headers Schema
200 OK Returns the subscription resource object and its associated properties. schema
404 Not Found Not Found. Subscription resources are not available (not created). schema

Responses

200 - Returns the subscription resource object and its associated properties.

Status: OK

Schema

SubscriptionInfo

404 - Not Found. Subscription resources are not available (not created).

Status: Not Found

Schema

Retrieves a list of subscriptions. (getSubscriptions)

GET /api/ocloudNotifications/v2/subscriptions

Get a list of subscription object(s) and their associated properties.

All responses

Code Status Description Has headers Schema
200 OK Returns the subscription resources and their associated properties that already exist. schema
400 Bad Request Bad request by the client. schema

Responses

200 - Returns the subscription resources and their associated properties that already exist.

Status: OK

Schema

[]SubscriptionInfo

400 - Bad request by the client.

Status: Bad Request

Schema

Models

Data

Array of JSON objects defining the information for the event.

Example:

{
"version": "v1.0",
"values": [{
"ResourceAddress": "/sync/sync-status/sync-state",
"data_type": "notification",
"value_type": "enumeration",
"value": "ACQUIRING-SYNC"
}, {
"ResourceAddress": "/sync/sync-status/sync-state",
"data_type": "metric",
"value_type": "decimal64.3",
"value": 100.3
}
}]
}

Properties

Name Type Go type Required Default Description Example
Values []DataValue []*DataValue
Version string string 1.0

DataValue

A json array of values defining the event.

Example:

{
"ResourceAddress": "/cluster/node/ptp",
"data_type": "notification",
"value_type": "enumeration",
"value": "ACQUIRING-SYNC"
}

Properties

Name Type Go type Required Default Description Example
DataType string string Type of value object. ( notification metric)
Resource string string The resource address specifies the Event Producer with a hierarchical path. Currently hierarchical paths with wild cards are not supported. /east-edge-10/Node3/sync/sync-status/sync-state
Value interface{} interface{} value in value_type format. HOLDOVER
ValueType string string The type format of the value property. enumeration

EventData

Event Data Model specifies the event Status Notification data model supported by the API. The current model supports JSON encoding of the CloudEvents.io specification for the event payload.

Properties

Name Type Go type Required Default Description Example
ID string string Identifies the event. The Event Producer SHALL ensure that source + id is unique for each distinct event e0dcb68b-2541-4d21-ab73-a222e42373c2
Source string string Identifies the context in which an event happened. /sync/sync-status/sync-state
SpecVersion string string The version of the CloudEvents specification which the event uses. This enables the interpretation of the context. 1.0
Time string string Time at which the event occurred. 2021-03-05T20:59:00.999999999Z
Type string string This attribute contains a value describing the type of event related to the originating occurrence. event.sync.sync-status.synchronization-state-change
data Data Data

SubscriptionInfo

SubscriptionInfo defines data types used for subscription.

Properties

Name Type Go type Required Default Description Example
EndPointURI string string Endpoint URI (a.k.a callback URI), e.g. http://localhost:8080/resourcestatus/ptp http://event-receiver/endpoint
ID string string Identifier for the created subscription resource. d1dd1770-e718-401e-ba32-cef05a286164
Resource string string The resource address specifies the Event Producer with a hierarchical path.
Format /{clusterName}/{siteName}(/optional/hierarchy/..)/{nodeName}/{(/optional/hierarchy)/resource}		 /east-edge-10/vdu3/o-ran-sync/sync-group/sync-status/sync-state
URILocation string string The URI location for querying the subscription created. http://localhost:9043/api/ocloudNotifications/v2/publishers/d1dd1770-e718-401e-ba32-cef05a286164

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