From 9bf0efc0175a71646a3a8769af0ac582537a67db Mon Sep 17 00:00:00 2001 From: Dysar Date: Fri, 22 Oct 2021 16:15:55 +0300 Subject: [PATCH] Added easier ways to create the clients, added example to the README --- README.md | 50 +++++++++++++++++++++- examples/example.go | 37 ++++++++-------- examples/sessionInfo/sessionInfoExample.go | 34 +++++++++++++++ pkg/api/client.go | 26 ++++++++--- pkg/api/customers/models.go | 2 +- pkg/api/partnerClient.go | 13 ++++++ pkg/api/requests.go | 4 +- 7 files changed, 137 insertions(+), 29 deletions(-) create mode 100644 examples/sessionInfo/sessionInfoExample.go diff --git a/README.md b/README.md index 6231f93..2ab8499 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,57 @@ ERPLY API Go SDK This SDK covers the [ERPLY API](https://erply.com/erply-api/) requests. +Quick Start +------ + +Initialize API client and make your first API call: +```go +package main + +import ( + "context" + "fmt" + + "github.com/erply/api-go-wrapper/pkg/api" +) + +func main() { + + //put your credentials here + const ( + username = "" + password = "" + clientCode = "" + ) + + cli, err := api.NewClientFromCredentials(username, password, clientCode, nil) + if err != nil { + panic(err) + } + + //configure the client to send the data payload in the request body instead of the query parameters. + //Using the request body eliminates the query size limitations imposed by the maximum URL length + cli.SendParametersInRequestBody() + + //init context to control the request flow + ctx, cancel := context.WithTimeout(context.Background(), 30 * time.Second) + defer cancel() + + //fetch the data from Erply API - in this example sales documents + salesDocs, err := cli.SalesManager.GetSalesDocuments(ctx, nil) + if err != nil { + panic(err) + } + + ... +} +``` + Client Structure ------ Majority of the request wrappers are available through the client. The client is described in `GoDoc` type `Client` and in `/pkg/api/client.go`. It is divided into sub-clients for each topic that the underlying API covers. -For now not all the requests are mapped to topics. Such request wrappers are in `/pkg/api` directory. +Not all the requests are mapped to topics. Such request wrappers are in `/pkg/api` directory. Some requests are accessible not from the client, but from the `auth` package of this SDK. They are covered in the example in `/examples` directory. Install @@ -33,6 +79,8 @@ Clients You can find the example in the `/examples` directory for the client initialization process + + Advanced listing diff --git a/examples/example.go b/examples/example.go index e12714d..4124cb4 100644 --- a/examples/example.go +++ b/examples/example.go @@ -3,46 +3,45 @@ package main import ( "context" "fmt" + "time" - "github.com/erply/api-go-wrapper/internal/common" "github.com/erply/api-go-wrapper/pkg/api" - "github.com/erply/api-go-wrapper/pkg/api/auth" ) func main() { + + //put your credentials here const ( username = "" password = "" clientCode = "" - partnerKey = "" ) - httpCli := common.GetDefaultHTTPClient() - sessionKey, err := auth.VerifyUser(username, password, clientCode, httpCli) - if err != nil { - panic(err) - } - sessInfo, err := auth.GetSessionKeyInfo(sessionKey, clientCode, httpCli) + cli, err := api.NewClientFromCredentials(username, password, clientCode, nil) if err != nil { panic(err) } - fmt.Println(sessInfo) - info, _ := auth.GetSessionKeyUser(sessionKey, clientCode, httpCli) - cli, err := api.NewClient(sessionKey, clientCode, nil) - if err != nil { - panic(err) - } - fmt.Println(info) + //indicate to the client that the request should add the data payload in the + //request body instead of using the query parameters. Using the request body eliminates the query size + //limitations imposed by the maximum URL length + cli.SendParametersInRequestBody() + + ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) + defer cancel() - endpoints, err := cli.ServiceDiscoverer.GetServiceEndpoints(context.Background()) + salesDocs, err := cli.SalesManager.GetSalesDocuments(ctx, nil) if err != nil { panic(err) } + fmt.Println(salesDocs) - fmt.Println(endpoints) + const ( + partnerKey = "" + ) - partnerCli, err := api.NewPartnerClient(sessionKey, clientCode, partnerKey, nil) + //partner client example + partnerCli, err := api.NewPartnerClientFromCredentials(username, password, clientCode, partnerKey, nil) if err != nil { panic(err) } diff --git a/examples/sessionInfo/sessionInfoExample.go b/examples/sessionInfo/sessionInfoExample.go new file mode 100644 index 0000000..a4e4286 --- /dev/null +++ b/examples/sessionInfo/sessionInfoExample.go @@ -0,0 +1,34 @@ +package main + +import ( + "fmt" + "github.com/erply/api-go-wrapper/internal/common" + "github.com/erply/api-go-wrapper/pkg/api/auth" +) + +func main() { + const ( + username = "" + password = "" + clientCode = "" + partnerKey = "" + ) + httpCli := common.GetDefaultHTTPClient() + + //get the session key + sessionKey, err := auth.VerifyUser(username, password, clientCode, httpCli) + if err != nil { + panic(err) + } + + //GetSessionKeyInfo allows you to get more information about the session if needed + sessInfo, err := auth.GetSessionKeyInfo(sessionKey, clientCode, httpCli) + if err != nil { + panic(err) + } + fmt.Println(sessInfo) + + //GetSessionKeyUser + info, _ := auth.GetSessionKeyUser(sessionKey, clientCode, httpCli) + fmt.Println(info) +} diff --git a/pkg/api/client.go b/pkg/api/client.go index cb60c4d..46d502c 100644 --- a/pkg/api/client.go +++ b/pkg/api/client.go @@ -52,19 +52,19 @@ type Client struct { ServiceDiscoverer servicediscovery.ServiceDiscoverer } -func (cl *Client) InvalidateSession() { - cl.commonClient.InvalidateSession() +func (c *Client) InvalidateSession() { + c.commonClient.InvalidateSession() } -func (cl *Client) GetSession() (sessionKey string, err error) { - return cl.commonClient.GetSession() +func (c *Client) GetSession() (sessionKey string, err error) { + return c.commonClient.GetSession() } //SendParametersInRequestBody indicates to the client that the request should add the data payload in the //request body instead of using the query parameters. Using the request body eliminates the query size //limitations imposed by the maximum URL length -func (cl *Client) SendParametersInRequestBody() { - cl.commonClient.SendParametersInRequestBody() +func (c *Client) SendParametersInRequestBody() { + c.commonClient.SendParametersInRequestBody() } //NewUnvalidatedClient returns a new Client without validating any of the incoming parameters giving the @@ -74,6 +74,20 @@ func NewUnvalidatedClient(sk, cc, partnerKey string, httpCli *http.Client) *Clie return newErplyClient(comCli) } +//NewClientFromCredentials makes a verifyUser Erply API call and initializes the client struct +func NewClientFromCredentials(username, password, clientCode string, customCli *http.Client) (*Client, error) { + if customCli == nil { + customCli = common.GetDefaultHTTPClient() + } + sessionKey, err := auth.VerifyUser(username, password, clientCode, customCli) + if err != nil { + return nil, err + } + + return NewClient(sessionKey, clientCode, customCli) +} + +// Deprecated // NewClient Takes three params: // sessionKey string obtained from credentials or jwt // clientCode erply customer identification number diff --git a/pkg/api/customers/models.go b/pkg/api/customers/models.go index a1d9356..5471055 100644 --- a/pkg/api/customers/models.go +++ b/pkg/api/customers/models.go @@ -84,7 +84,7 @@ type ( LastLogin string `json:"webshopLastLogin"` // Detailed info - PriceListID int `json:"priceListID"` + PriceListID int `json:"priceListID"` PriceListID2 int `json:"priceListID2"` PriceListID3 int `json:"priceListID3"` } diff --git a/pkg/api/partnerClient.go b/pkg/api/partnerClient.go index c37ccac..474216e 100644 --- a/pkg/api/partnerClient.go +++ b/pkg/api/partnerClient.go @@ -12,6 +12,19 @@ type PartnerClient struct { PartnerTokenProvider auth.PartnerTokenProvider } +func NewPartnerClientFromCredentials(username, password, clientCode, partnerKey string, customCli *http.Client) (*PartnerClient, error) { + if customCli == nil { + customCli = common.GetDefaultHTTPClient() + } + sessionKey, err := auth.VerifyUser(username, password, clientCode, customCli) + if err != nil { + return nil, err + } + + return NewPartnerClient(sessionKey, clientCode, partnerKey, customCli) +} + +// Deprecated func NewPartnerClient(sessionKey, clientCode, partnerKey string, customCli *http.Client) (*PartnerClient, error) { if sessionKey == "" || clientCode == "" || partnerKey == "" { return nil, errors.New("sessionKey, clientCode and partnerKey are required") diff --git a/pkg/api/requests.go b/pkg/api/requests.go index 5022008..50fe746 100644 --- a/pkg/api/requests.go +++ b/pkg/api/requests.go @@ -81,7 +81,7 @@ func (c *Client) GetEmployees(ctx context.Context, filters map[string]string) ([ return res.Employees, nil } -func (cli *Client) GetEmployeesBulk(ctx context.Context, bulkFilters []map[string]interface{}, baseFilters map[string]string) (GetEmployeesResponseBulk, error) { +func (c *Client) GetEmployeesBulk(ctx context.Context, bulkFilters []map[string]interface{}, baseFilters map[string]string) (GetEmployeesResponseBulk, error) { var bulkResp GetEmployeesResponseBulk bulkInputs := make([]common.BulkInput, 0, len(bulkFilters)) for _, bulkFilterMap := range bulkFilters { @@ -90,7 +90,7 @@ func (cli *Client) GetEmployeesBulk(ctx context.Context, bulkFilters []map[strin Filters: bulkFilterMap, }) } - resp, err := cli.commonClient.SendRequestBulk(ctx, bulkInputs, baseFilters) + resp, err := c.commonClient.SendRequestBulk(ctx, bulkInputs, baseFilters) if err != nil { return bulkResp, err }