api

README

api

• Project README
• Release/Build Status
• Changelog
• License
• Contribution Guidelines
• Code of Conduct
• Secure Coding Guidelines

Specification

Description

The api package contains all API functionality of Device Management Service (DMS). DMS exposes various endpoints through which its different functionalities can be accessed.

Structure and Organisation

Here is quick overview of the contents of this directory:

• README: Current file which is aimed towards developers who wish to use and modify the api functionality.

• api.go: This file contains router setup using Gin framework. It also applies Cross-Origin Resource Sharing (CORS) middleware and OpenTelemetry middleware for tracing. Further it lists down the endpoint URLs and the associated handler functions.

• actor.go: Contains endpoints for actor interaction.

Functionality

Configuration

The REST server by default binds to 127.0.0.1 on port 9999. The configuration file dms_config.json can be used to change to a different address and port.

The parameters rest.port and rest.addr define the port and the address respectively.

You can use the following format to construct the URL for accessing API endpoints

http://localhost:<port>/api/v1/<endpoint>

Currently, all endpoints are under the /actor path

/actor/handle

Retrieve actor handle with ID, DID, and inbox address

Item	Value
endpoint:	/actor/handle
method:	HTTP GET
output:	Actor Handle

Response:

{
    "id": <actor_id>,
    "did" : <actor_did>,
    "addr" : <inbox_address>
}

/actor/send

Send a message to actor

Item	Value
endpoint:	/actor/handle
method:	HTTP POST
output:	{"message": "message sent"}

The request should be an enveloped message

{
    "to": {
        "id": <actor_id>,
        "did" : <actor_did>,
        "addr" : <inbox_address>
    },
    "be": <behavior>,
    "from": {
        "id": <actor_id>,
        "did" : <actor_did>,
        "addr" : <inbox_address>
    },
    "nonce": <nonce>,
    "opt": {
        "cont": <topic_to_publish_to>,
        "exp": <time_to_expire>
    },
    "msg": <message>,
    "cap": <capability>,
    "sig": <signature>
}

/actor/invoke

Invoke actor with message

Item	Value
endpoint:	/actor/invoke
method:	HTTP POST
output:	Enveloped Response or if error {"error": "<error message>"}

The request should be an enveloped message

{
    "to": {
        "id": <actor_id>,
        "did" : <actor_did>,
        "addr" : <inbox_address>
    },
    "be": <behavior>,
    "from": {
        "id": <actor_id>,
        "did" : <actor_did>,
        "addr" : <inbox_address>
    },
    "nonce": <nonce>,
    "opt": {
        "cont": <topic_to_publish_to>,     // needs to be specified for invoke
        "exp": <time_to_expire>
    },
    "msg": <message>,
    "cap": <capability>,
    "sig": <signature>
}

/actor/broadcast

Broadcast message to actors

Item	Value
endpoint:	/actor/broadcast
method:	HTTP POST
output:	Enveloped Response or if error {"error": "<error message>"}

The request should be an enveloped message

{
    "to": {},                                 // should be empty for broadcast
    "be": <behavior>,
    "from": {
        "id": <actor_id>,
        "did" : <actor_did>,
        "addr" : <inbox_address>
    },
    "nonce": <nonce>,
    "opt": {
        "topic": <topic_to_publish_to>,
        "exp": <time_to_expire>
    },
    "msg": <message>,
    "cap": <capability>,
    "sig": <signature>
}

For more details on these Actor API endpoints, refer to the cmd/actor package on how the they are used.

Documentation

Index

• type Server
  • func NewServer(config *ServerConfig) *Server
  • func (rs *Server) ActorBroadcast(c *gin.Context)
  • func (rs *Server) ActorHandle(c *gin.Context)
  • func (rs *Server) ActorInvoke(c *gin.Context)
  • func (rs *Server) ActorSendMessage(c *gin.Context)
  • func (rs *Server) HealthCheck(c *gin.Context)
  • func (rs *Server) Run() error
  • func (rs *Server) SetupRoutes()
• type ServerConfig

Types

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server represents a REST server

func NewServer

func NewServer(config *ServerConfig) *Server

NewServer creates a new REST server

func (*Server) ActorBroadcast

func (rs *Server) ActorBroadcast(c *gin.Context)

ActorBroadcast godoc

     @Summary		Broadcast message to actors
			@Description	Broadcast message to actors
			@Tags			actor
			@Accept			json
			@Produce		json
		  @Param			message	body	actor.Envelope	true	"Message to send"
			@Success		200	{object}	object	"received responses"
	   @Failure		400	{object}	object	"invalid request data"
			@Failure		500	{object}	object	"host node hasn't yet been initialized"
			@Failure		500	{object}	object	"failed to marshal message"
			@Failure		500	{object}	object	"failed to publish message"
			@Router			/actor/broadcast [post]

func (*Server) ActorHandle

func (rs *Server) ActorHandle(c *gin.Context)

ActorHandle godoc

@Summary		Retrieve actor handle
@Description	Retrieve actor handle with ID, DID, and inbox address
@Tags			actor
@Produce		json
@Success		200	{object}	actor.Handle
@Failure		500	{object}	object	"host node hasn't yet been initialized"
@Failure		500	{object}	object	"handle id is invalid"
@Router			/actor/handle [get]

func (*Server) ActorInvoke

func (rs *Server) ActorInvoke(c *gin.Context)

ActorInvoke godoc

	@Summary		Invoke actor
	@Description	Invoke actor with message
	@Tags			actor
	@Accept			json
	@Produce		json
 @Param			message	body	actor.Envelope	true	"Message to send"
	@Success		200	{object}	object	"response message"
 @Failure		400	{object}	object	"invalid request data"
	@Failure		500	{object}	object	"host node hasn't yet been initialized"
	@Failure		500	{object}	object	"failed to marshal message"
	@Failure		500	{object}	object	"destination address can't be resolved"
	@Failure		500	{object}	object	"failed to send message to destination"
	@Router			/actor/invoke [post]

func (*Server) ActorSendMessage

func (rs *Server) ActorSendMessage(c *gin.Context)

ActorSendMessage godoc

	@Summary		Send message to actor
	@Description	Send message to actor
	@Tags			actor
	@Accept			json
	@Produce		json
 @Param			message	body	actor.Envelope	true	"Message to send"
	@Success		200	{object}	object	"message sent"
 @Failure		400	{object}	object	"invalid request data"
	@Failure		500	{object}	object	"host node hasn't yet been initialized"
	@Failure		500	{object}	object	"failed to marshal message"
	@Failure		500	{object}	object	"destination address can't be resolved"
	@Failure		500	{object}	object	"failed to send message to destination"
	@Router			/actor/send [post]

func (*Server) HealthCheck

func (rs *Server) HealthCheck(c *gin.Context)

HealthCheck is a health check endpoint

func (*Server) Run

func (rs *Server) Run() error

Run starts the server on the specified port

func (*Server) SetupRoutes

func (rs *Server) SetupRoutes()

SetupRoutes sets up all the endpoint routes

type ServerConfig

type ServerConfig struct {
	P2P         network.Network
	Onboarding  *onboarding.Onboarding
	Resource    types.ResourceManager
	Middlewares []gin.HandlerFunc
	Port        uint32
	Addr        string
}