LogoLogo
WebsiteTechnical Discussions
Developer documentation
Developer documentation
  • Public Technical Documentation
    • device-management-service
      • main
        • actor
        • api
        • cmd
          • actor
          • cap
        • db
          • repositories
            • clover
        • dms
          • behaviors
          • jobs
          • node
          • onboarding
          • resources
        • docs
          • deployments
          • onboarding
          • private_network
        • executor
          • docker
          • firecracker
          • background_tasks
          • config
          • hardware
        • maint-scripts
        • network
          • libp2p
        • observability
        • specs
          • basic_controller
          • s3
          • volume
          • integration
        • tokenomics
        • types
        • utils
          • validate
      • release
        • actor
        • api
        • cmd
          • actor
          • cap
        • db
          • repositories
            • clover
        • dms
          • behaviors
          • hardware
          • jobs
          • node
          • onboarding
          • resources
        • docs
          • deployments
          • onboarding
          • private_network
        • executor
          • docker
          • firecracker
        • internal
          • background_tasks
          • config
        • maint-scripts
        • network
          • libp2p
        • observability
        • plugins
        • specs
        • storage
          • basic_controller
          • s3
          • volume
        • test
        • tokenomics
        • types
        • utils
          • validate
    • solutions
      • asi-node
        • main
          • demos
            • ocap_auth
              • ansible
              • videos
          • did-auth-use-scenarios
            • create-a-hosting-deployment
            • make-a-payment
            • manage-dids-and-ocaps
            • register-an-ai-agent
            • submit-a-compute-job
          • pilots
            • asi-create-authentication-poc
        • release
      • nunet-appliance
        • main
        • release
    • test-suite
      • main
        • cicd
          • tests
            • feature_environment
          • cli
          • dms-on-lxd
            • local
        • environments
          • development
          • feature
          • production
          • staging
        • infrastructure
          • cloud-init
          • dms-on-lxd
          • nginx
        • lib
        • stages
          • dependency_scanning
          • functional_tests
          • integration_tests
          • load_tests
          • regression_tests
          • security_tests_1
          • security_tests_2
          • security_tests_live
          • unit_tests
          • user_acceptance_tests
      • release
        • cicd
          • tests
            • feature_environment
          • cli
          • dms-on-lxd
            • local
        • environments
          • development
          • feature
          • production
          • staging
        • infrastructure
          • cloud-init
          • dms-on-lxd
          • nginx
        • lib
        • stages
          • dependency_scanning
          • functional_tests
          • integration_tests
          • load_tests
          • regression_tests
          • security_tests_1
          • security_tests_2
          • security_tests_live
          • unit_tests
          • user_acceptance_tests
    • team-processes-and-guidelines
      • main
        • best_practices
        • ci_cd_pipeline
        • community_feedback_process
        • contributing_guidelines
        • git_workflows
        • nunet_test_process_and_environments
        • secure_coding_guidelines
        • specification_and_documentation
        • team_process
          • a_project_management
          • b_ceremonies_artifacts
          • c_drum_buffer_rope
          • d_development_process
          • e_culture_rules
          • f_mr_review
        • vulnerability_management
          • devsecops_maturity_models
          • nunet_security_pipeline
          • secret_management
          • sop_security_mr_review
Powered by GitBook
On this page
  • api
  • Specification
Export as PDF
  1. Public Technical Documentation
  2. device-management-service
  3. release

api

PreviousactorNextcmd

Last updated 9 hours ago

Last updated: 2025-05-15 01:08:25.495135 File source:

api

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:

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

  • : 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.

  • : 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 on how the they are used.

link on GitLab
Project README
Release/Build Status
Changelog
License
Contribution Guidelines
Code of Conduct
Secure Coding Guidelines
README
api.go
actor.go
cmd/actor package