api

Documentation

Overview

Package api provides HTTP API functions to access Sylvia-IoT coremgr APIs.

Client is a wrapped HTTP client that is used for Sylvia-IoT `coremgr` APIs with the following features:

• Use `client_credentials` grant type to get access token.
• It is REQUIRED to register `private` clients (with secret).
• It is RECOMMENDED to use the `service` role for clients, not to use `admin`, `manager` or `user` roles.
• Refresh token automatically to integrate network servers and application servers (or adapters) conviniently because they do not need to do multiple operations for one API request.

Here is an example to create a client to access an API:

import (
	"github.com/woofdogtw/sylvia-iot-go/sdk/api"
)

func main() {
	opts := api.ClientOptions{
		AuthBase:     "http://localhost:1080/auth",
		CoremgrBase:  "http://localhost:1080/coremgr",
		ClientID:     "ADAPTER_CLIENT_ID",
		ClientSecret: "ADAPTER_CLIENT_SECRET",
	}
	client, _ := api.NewClient(opts)
	client.Request("GET", "/api/v1/user", nil)
}

Index

• func GetUser(c *Client) (*GetUserResData, *ApiError)
• type ApiError
  • func UpdateUser(c *Client, data PatchUserReqData) *ApiError
  • func (e *ApiError) Error() string
• type Client
  • func NewClient(opts ClientOptions) (*Client, error)
  • func (c *Client) Request(method string, apiPath string, body []byte) (statusCode int, resBody []byte, err error)
• type ClientOptions
• type GetUserResData
• type Oauth2Error
  • func (e *Oauth2Error) Error() string
• type PatchUserReqData

Functions

func GetUser

func GetUser(c *Client) (*GetUserResData, *ApiError)

`GET /coremgr/api/v1/user`

Types

type ApiError

type ApiError struct {
	// Error code.
	Code string `json:"code"`
	// Detail message.
	Message string `json:"message,omitempty"`
}

The Sylvia-IoT API error response.

func UpdateUser

func UpdateUser(c *Client, data PatchUserReqData) *ApiError

`PATCH /coremgr/api/v1/user`

func (*ApiError) Error

func (e *ApiError) Error() string

type Client

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

The HTTP client to request Sylvia-IoT APIs. With this client, you do not need to handle 401 refresh token flow.

func NewClient

func NewClient(opts ClientOptions) (*Client, error)

Create an instance.

func (*Client) Request

func (c *Client) Request(method string, apiPath string,
	body []byte) (statusCode int, resBody []byte, err error)

Execute a Sylvia-IoT API request.

• `apiPath` is the relative path (of the coremgr base) the API with query string. For example: `/api/v1/user/list?contains=word`, the client will do a request with `http://coremgr-host/coremgr/api/v1/user/list?contains=word` URL.
• `body` MUST be JSON format.

type ClientOptions

type ClientOptions struct {
	// `sylvia-iot-auth` base path with scheme. For example `http://localhost:1080/auth`
	AuthBase string
	// `sylvia-iot-coremgr` base path with scheme. For example `http://localhost:1080/coremgr`
	CoremgrBase string
	// Client ID.
	ClientID string
	// Client secret.
	ClientSecret string
}

Options of the HTTP client [`Client`] that contains OAuth2 information.

type GetUserResData

type GetUserResData struct {
	UserID     string
	Account    string
	CreatedAt  time.Time
	ModifiedAt time.Time
	VerifiedAt time.Time // may be zero time
	Roles      map[string]bool
	Name       string
	Info       map[string]interface{}
}

type Oauth2Error

type Oauth2Error struct {
	// Error code.
	ErrorCode string `json:"error"`
	// Detail message.
	ErrorMessage string `json:"error_message,omitempty"`
}

The OAuth2 error response.

func (*Oauth2Error) Error

func (e *Oauth2Error) Error() string

type PatchUserReqData

type PatchUserReqData struct {
	// Empty will not change the original setting.
	Password string `json:"password,omitempty"`
	// The display name.
	//
	// `Note`: `nil` will not change setting. Empty string overwrite the original setting.
	Name *string `json:"name,omitempty"`
	// `nil` will not change the original setting.
	Info map[string]interface{} `json:"info,omitempty"`
}