Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
504 lines (502 sloc) 13.9 KB
swagger: '2.0'
info:
description: >-
This is the REST API for the User Services Platform (USP) Controller. This
is how an external entity can interact with a USP Controller to retrieve
information from or configure a USP Agent.
version: 1.0.0
title: User Services Platform - Controller API
termsOfService: 'http://usp.technology/terms/'
contact:
email: info@broadband-forum.org
license:
name: Apache 2.0
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
host: swagger.usp.technology
basePath: /v2
tags:
- name: agents
description: Interact with USP Agents
schemes:
- http
paths:
'/agents':
post:
tags:
- agents
summary: Create a USP Agent with a Given Endpoint ID
description: Create a new USP Agent with a Given Endpoint ID
operationId: createAgent
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
description: Details about the new USP Agent
required: true
schema:
$ref: '#/definitions/CreateAgentDetails'
responses:
'201':
description: USP Agent created
'400':
description: USP Agent creation failed
'/agents/{endpointID}':
get:
tags:
- agents
summary: Get USP Agent Details
description: Retrieve details related to a specific USP Agent
operationId: getAgentDetails
consumes:
- application/json
produces:
- application/json
parameters:
- name: endpointID
in: path
description: USP Agent Endpoint ID
required: true
type: string
responses:
'200':
description: Successful operation
schema:
$ref: '#/definitions/AgentDetails'
'404':
description: USP Agent not found
put:
tags:
- agents
summary: Update a USP Agent
description: Update the details of a USP Agent
operationId: updateAgent
consumes:
- application/json
produces:
- application/json
parameters:
- name: endpointID
in: path
description: USP Agent Endpoint ID
required: true
type: string
- in: body
name: body
description: USP Agent details that need to be updated
required: true
schema:
$ref: '#/definitions/AgentDetails'
responses:
'204':
description: USP Agent updates applied
'400':
description: USP Agent update failed
'404':
description: USP Agent not found
delete:
tags:
- agents
summary: Delete a USP Agent
description: Remove an existing USP Agent
operationId: deleteAgent
consumes:
- application/json
produces:
- application/json
parameters:
- name: endpointID
in: path
description: USP Agent Endpoint ID
required: true
type: string
responses:
'204':
description: USP Agent removed
'400':
description: USP Agent removal failed
'404':
description: USP Agent not found
'/agents/{endpointID}/status':
get:
tags:
- agents
summary: Get USP Agent Status
description: Retrieve communications status of a specific USP Agent
operationId: getAgentStatus
consumes:
- application/json
produces:
- application/json
parameters:
- name: endpointID
in: path
description: USP Agent Endpoint ID
required: true
type: string
responses:
'200':
description: Successful operation
schema:
$ref: '#/definitions/AgentStatus'
'404':
description: USP Agent not found
'/agents/{endpointID}/associatedAgents':
get:
tags:
- agents
summary: Search for USP Agents associated to this USP Agent
description: Search for USP Agents associated to this USP Agent
operationId: searchAgents
consumes:
- application/json
produces:
- application/json
parameters:
- name: endpointID
in: path
description: USP Agent Endpoint ID
required: true
type: string
responses:
'200':
description: Successful operation
schema:
$ref: '#/definitions/AgentSearchResults'
'404':
description: USP Agent not found
'/agents/{endpointID}/serviceElements':
post:
tags:
- agents
summary: Create Service Element instance on a USP Agent
description: Update the USP Agent's configuration by creating a new instance of the specified Service Element
operationId: createAgentServiceElement
consumes:
- application/json
produces:
- application/json
parameters:
- name: endpointID
in: path
description: USP Agent Endpoint ID
required: true
type: string
- in: body
name: body
description: Service Element object that needs to be created on the USP Agent
required: true
schema:
$ref: '#/definitions/CreateServiceElementDetail'
responses:
'201':
description: Service Element instance created
'400':
description: Service Element instance creation failed
'404':
description: USP Agent not found
'/agents/{endpointID}/serviceElements/{name}':
get:
tags:
- agents
summary: Get Service Element instance by Name from USP Agent
description: Retrieve an instance of the specified Service Element from a specific USP Agent
operationId: getAgentServiceElement
produces:
- application/json
parameters:
- name: endpointID
in: path
description: USP Agent Endpoint ID
required: true
type: string
- name: name
in: path
description: Service Element Name
required: true
type: string
- in: body
name: body
description: The identifier of the Service Element to remove
required: true
schema:
$ref: '#/definitions/ServiceElementIdentifier'
responses:
'200':
description: Successful operation
schema:
$ref: '#/definitions/ServiceElementDetail'
'400':
description: Service Element not found
'404':
description: USP Agent not found
patch:
tags:
- agents
summary: Update Service Element instance by Name on a USP Agent
description: Update the USP Agent's configuration with the given instance of the specified Service Element
operationId: updateAgentServiceElements
consumes:
- application/json
produces:
- application/json
parameters:
- name: endpointID
in: path
description: USP Agent Endpoint ID
required: true
type: string
- name: name
in: path
description: Service Element Name
required: true
type: string
- in: body
name: body
description: Service Element objects that need to be configured on the USP Agent
required: true
schema:
$ref: '#/definitions/ServiceElementDetail'
responses:
'204':
description: Service Element updates applied
'400':
description: Service Element update failed
'404':
description: USP Agent not found
delete:
tags:
- agents
summary: Delete Service Element instance by Name from USP Agent
description: Update the USP Agent's configuration by removing an existing instance of the specified Service Element
operationId: deleteAgentServiceElement
consumes:
- application/json
produces:
- application/json
parameters:
- name: endpointID
in: path
description: USP Agent Endpoint ID
required: true
type: string
- name: name
in: path
description: Service Element Name
required: true
type: string
- in: body
name: body
description: The identifier of the Service Element to remove
required: true
schema:
$ref: '#/definitions/ServiceElementIdentifier'
responses:
'204':
description: Service Element instance removed
'400':
description: Service Element instance removal failed
'404':
description: USP Agent not found
'/agents/{endpointID}/commands':
post:
tags:
- agents
summary: Execute Service Element Action on USP Agent
description: Execute a Service Element Action on a USP Agent
operationId: executeAgentServiceElementAction
consumes:
- application/json
produces:
- application/json
parameters:
- name: endpointID
in: path
description: USP Agent Endpoint ID
required: true
type: string
- in: body
name: body
description: Service Element action to execute on the USP Agent
required: true
schema:
$ref: '#/definitions/ServiceElementAction'
responses:
'201':
description: Asynchronous Action Invoked
schema:
$ref: '#/definitions/AsyncActionResults'
'202':
description: Synchronous Action Invoked
schema:
$ref: '#/definitions/ActionResults'
'400':
description: Service Element Action invocation failed
'404':
description: USP Agent not found
'/agents/{endpointID}/commands/{asyncRequestID}':
get:
tags:
- agents
summary: Get Asynchronous Service Element Action results.
description: Retrieve the asynchronous results of a Service Element Action
operationId: getAgentServiceElementActionResults
produces:
- application/json
parameters:
- name: endpointID
in: path
description: USP Agent Endpoint ID
required: true
type: string
- name: asyncRequestID
in: path
description: Service Element Asynchronous Action Request ID
required: true
type: string
responses:
'200':
description: Successful operation
schema:
$ref: '#/definitions/ActionResults'
'400':
description: Service Element Asynchronous Action Request ID not found
'404':
description: USP Agent not found
definitions:
CreateAgentDetails:
type: object
properties:
endpointID:
description: Endpoint ID of USP Agent
type: string
mtpToUse:
type: string
enum:
- CoAP
- STOMP
- WebSockets
communicationsAddress:
description: URL (CoAP or WebSockets) or STOMP Destination of USP Agent
type: string
supportedServiceElements:
description: >-
The Service Elements supported by the USP Agent (if known by the USP
Controller)
type: array
items:
type: string
AgentDetails:
type: object
properties:
mtpToUse:
type: string
enum:
- CoAP
- STOMP
- WebSockets
communicationsAddress:
description: URL (CoAP or WebSockets) or STOMP Destination of USP Agent
type: string
supportedServiceElements:
description: >-
The Service Elements supported by the USP Agent (if known by the USP
Controller)
type: array
items:
type: string
AgentSearchResults:
type: object
properties:
outputArgs:
type: array
items:
description: List of USP Endpoint IDs
type: string
AgentStatus:
type: object
properties:
communicationsStatus:
type: string
enum:
- Available
- Unavailable
- Unknown
default: Unknown
AsyncActionResults:
type: object
properties:
asyncRequestID:
type: string
ActionResults:
type: object
properties:
outputArgs:
type: array
items:
type: object
properties:
argName:
type: string
argValue:
type: string
ServiceElementAction:
type: object
properties:
name:
description: Name of the Service Element
type: string
inputArgs:
type: array
items:
type: object
properties:
argName:
type: string
argValue:
type: string
ServiceElementIdentifier:
type: object
properties:
uniqueKeyList:
type: array
items:
type: object
properties:
elementProperty:
type: string
elementValue:
type: string
CreateServiceElementDetail:
type: object
properties:
name:
description: Service Element Name
type: string
identifier:
$ref: '#/definitions/ServiceElementIdentifier'
propertyList:
type: array
items:
type: object
properties:
elementProperty:
type: string
elementValue:
type: string
ServiceElementDetail:
type: object
properties:
identifier:
$ref: '#/definitions/ServiceElementIdentifier'
propertyList:
type: array
items:
type: object
properties:
elementProperty:
type: string
elementValue:
type: string
You can’t perform that action at this time.