openapi

README

a tool to provide third-party apis

a common tool for providing api to third-party users

theoretically the tool is compatible with all kinds of web framework and iris and gin is the recommend web framework.

for server

before you use

if you use the default sql implementation, you should create a table first of course, you can define your own table as long as you point out the right way to get your actual secret

CREATE TABLE `app` (
  `app_key` varchar(32) NOT NULL,
  `app_secret` varchar(128) NOT NULL,
  `created` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `updated` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`app_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

another way for you to get the secret is you can implement the interface here

// the interface to get the secret
type SecretKeeper interface {
	GetSecret() (string, error)
}

using it in your web framework

create a middle ware for some web framework

// create a middle ware for iris
func OpenApiHandler(ctx iris.Context) {

    //sign header? to prevent header being modified by others
    // openapi.SignHeader(true)

	req := ctx.Request()
	// you can put the key somewhere in the header or url params
	r, err := openapi.CheckValid(req,
	// default implementation is via sql, to fetch the secrect
	    openapi.SqlSecretKeeper{
            Db:        store.GetDb(),
            TableName: "app",       // the name of table where you store all your app  keys and  secretcs
            KeyCol:    "app_key",   // the column name of the app keys
            SecretCol: "app_secret", // the column name of the app secrets
	})
	logError(err)
	if r {
	    // verfy success, continue the request
		ctx.Next()
	} else {
	    // verify fail, stop the request and return
		ctx.Text(err.Error())
		ctx.StopExecution()
		return
	}
}

use it on some kind of api groups

// use the middle ware somewhere
// so all the apis under this group should be
// called with signed result and app key
	openApiGroup := app.Party("/open")
	openApiGroup.Use(OpenApiHandler)
	{
		openApiGroup.Get("/app", func(ctx iris.Context) {
			ctx.Text("success")
		})
	}

for client

Use client provided by the package

func GetSomeAPIResult() {
    client := openapi.DefaultClient("key....", "a9f83xa3sjh7xad")
    result, err := client.Get("/api/testdata")
    result, err := client.Post("/api/testdata", "post body")
    // ...
    // result is the data from remote api, and the remote api is enforced
    // by this very open api handler
}

how to build custom clients?

1. get current time in millis and append it to the existing parameters ?time=1553759639794
2. add app_key param to your url params
3. take out all the headers and params and sort them
4. connect the sorted params to a string use x=y& to one string
5. sign the connected string and append the param &sign={sign_result} to your url parameter
6. send the request

then you will succeed.

how to sign

we only provide sha256 as the sign method of the string content

// sign with sha 256
func Sign(content, key string) string {
	h := sha256.New()
	h.Write([]byte(content + key))
	return fmt.Sprintf("%x", h.Sum(nil))
}

how to sort and connect

sort order is ascending

func buildParams(params Pairs) string {
	sort.Sort(params)
	var result string
	for _, v := range params {
		r := v.Key + "=" + v.Value + "&"
		result += r
	}
	return result
}

Documentation

Index

• Constants
• func CheckValid(req *http.Request, keeper SecretKeeper) (bool, error)
• func New(keeper SecretKeeper, sucFunc, failFunc func()) *openApi
• func Sign(content, key string) string
• func SignHeader(s bool)
• type Client
  • func DefaultClient(key, sec string) *Client
  • func NewClient(keeper SecretKeeper, key string) *Client
  • func (c *Client) Delete(uri, body string, headers ...http.Header) (string, error)
  • func (c *Client) Get(uri string, headers ...http.Header) (string, error)
  • func (c *Client) Post(uri, body string, headers ...http.Header) (string, error)
  • func (c *Client) Put(uri, body string, headers ...http.Header) (string, error)
• type DefaultProvider
  • func (dp DefaultProvider) GetSecret(key string) (string, error)
• type KvPair
• type Pairs
  • func (p Pairs) Len() int
  • func (p Pairs) Less(i, j int) bool
  • func (p Pairs) Swap(i, j int)
• type PgSqlSecretKeeper
  • func (s PgSqlSecretKeeper) GeneratePair() *KvPair
  • func (s PgSqlSecretKeeper) GetSecret(key string) (string, error)
• type SecretKeeper
• type SqlSecretKeeper
  • func (s SqlSecretKeeper) GeneratePair() *KvPair
  • func (s SqlSecretKeeper) GetSecret(key string) (string, error)

Constants

const (
	EmptyString = ""
)

Functions

func CheckValid

func CheckValid(req *http.Request, keeper SecretKeeper) (bool, error)

CheckValid to check if the request is valid from the signing key

func New

func New(keeper SecretKeeper, sucFunc, failFunc func()) *openApi

func Sign

func Sign(content, key string) string

Sign with sha 256

func SignHeader

func SignHeader(s bool)

SignHeader whether to sign http request header or not

Types

type Client

type Client struct {
	Key    string
	Keeper SecretKeeper
}

func DefaultClient

func DefaultClient(key, sec string) *Client

func NewClient

func NewClient(keeper SecretKeeper, key string) *Client

func (*Client) Delete

func (c *Client) Delete(uri, body string, headers ...http.Header) (string, error)

func (*Client) Get

func (c *Client) Get(uri string, headers ...http.Header) (string, error)

func (*Client) Post

func (c *Client) Post(uri, body string, headers ...http.Header) (string, error)

func (*Client) Put

func (c *Client) Put(uri, body string, headers ...http.Header) (string, error)

type DefaultProvider

type DefaultProvider struct {
	AppKey    string
	AppSecret string
}

func (DefaultProvider) GetSecret

func (dp DefaultProvider) GetSecret(key string) (string, error)

type KvPair

type KvPair struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

KvPair is a simple struct for kv pair

type Pairs

type Pairs []KvPair

Pairs is the slice of the KvPair

func (Pairs) Len

func (p Pairs) Len() int

func (Pairs) Less

func (p Pairs) Less(i, j int) bool

func (Pairs) Swap

func (p Pairs) Swap(i, j int)

type PgSqlSecretKeeper

type PgSqlSecretKeeper struct {
	Db        *sql.DB // the client to access database
	TableName string  // the table where the secret stores
	KeyCol    string  // the column name of the key
	SecretCol string  // the column name of the secret
}

default provided sql

func (PgSqlSecretKeeper) GeneratePair

func (s PgSqlSecretKeeper) GeneratePair() *KvPair

func (PgSqlSecretKeeper) GetSecret

func (s PgSqlSecretKeeper) GetSecret(key string) (string, error)

get secret from a sql data source

type SecretKeeper

type SecretKeeper interface {
	GetSecret(key string) (string, error)
}

the interface to get the secret

type SqlSecretKeeper

type SqlSecretKeeper struct {
	Db        *sql.DB // the client to access database
	TableName string  // the table where the secret stores
	KeyCol    string  // the column name of the key
	SecretCol string  // the column name of the secret
}

default provided sql

func (SqlSecretKeeper) GeneratePair

func (s SqlSecretKeeper) GeneratePair() *KvPair

func (SqlSecretKeeper) GetSecret

func (s SqlSecretKeeper) GetSecret(key string) (string, error)

get secret from a sql data source