Using APIs in the Lambda Suite

This article provides an introduction into using APIs for your Lambda Suite.

TOPICS


Introduction to Suite APIs

The Lambda Suite APIs provides developers with the means to use web services that communicate with programs in the Lambda Suite.

Key features include:

  • Support for REST (Representational State Transfer)
  • Two types of authentication: 
    • Token-based authentication
    • OAuth-based authentication
    • All accounts and integrations are assigned resources that they have access to. The API framework checks that any call has the authorization to perform the request.
    • The framework is based on a create, read, update, and search model.

    Back to TOPICS


    Use REST APIs

    The Lambda Suite API defines a set of functions that a developer can use to perform requests and receive responses. These interactions are performed using the HTTPS protocol. 

    The caller issues an HTTPS request, which contains the following elements:

    1.  An HTTPS header that provides authentication and other instructions.

    2.  A verb, which can be one of GET or POST.

    3.  An endpoint, which is a Uniform Resource Indicator (URI) that identifies the server, the web service, and the resource being acted on.

    4.  The call payload, which is a set of input parameters and attributes that you supply with the request.

    The Suite will return a response payload, as well as an HTTPS status code.

    This article introduces REST command concepts. It describes how to authenticate and run REST API calls. You can run REST web API calls through cURL commands or a REST client.

    Back to TOPICS


    Constructing a Request

    The following table and sections describe web API call elements:

    Element Specifies
    HTTP Verb The action to perform against the endpoint.
    Endpoint A combination of the server that fulfills a request, the web service, and the resource against which the request is being made.
    HTTP Headers The authentication token, the call request and response formats, and other information.
    Call Payload A set of input parameters and attributes that you supply with the request. API operations have both required and optional inputs. You can specify input parameters in the URI and input attributes in a request body. You can specify a JSON- or XML-formatted request body.

    HTTP Verb

    Specify one of these HTTP verbs in the request:

    GET: Requests transfer of a current representation of the target resource. If you omit the verb, GET is the default.

    POST: Requests that the origin server accept the representation enclosed in the request as data to be processed by the target resource.

    Endpoint

    An endpoint is a combination of the server that fulfills a request, the web service, the store code, the resource against which the request is being made, and any template parameters.

    For example, in the http://lambdastore.com/index/php/rest/all/V1/orders{id} endpoint, the server is lambdastore.com/index/php, the web service is rest, the resource is /V1/orders/{id}, and the template parameter is id. A store code can have one of the following values:

    • The store's assigned store code.
    • /all/. This value only applies to endpoints defined in the CMS and Product modules. If this value is specified, the API call affects all of the stores.

    HTTP Headers

    Specify one or more of the following HTTP headers in your web API calls:

    HTTP Header Description Syntax
    Authorization Required. Specifies the authentication token that proves you as the owner of a Suiteaccount. You specify the token in the Authorization request header with the Bearer HTTP authorization scheme.

    Authorization: Bearer <TOKEN>

    <TOKEN> is the authentication token returned by the token service. See Authentication.

    Accept Optional. Specifies the format of the response body. Default is JSON.

    Accept: application/<FORMAT>

    <FORMAT> is either JSON or XML.

    Content-Type Required for operations with a request body. Specifies the format of the request body.

    Content-Type: application/<FORMAT>

    <FORMAT> is either JSON or XML.

    Call Payload

    The call payload is a set of input parameters and attributes that you supply with the request. API operations have both required and optional inputs.

    You specify input parameters in the URI. For example, in the GET/V1/customers/:customerId URI, you must specify the customer Id template parameter. This parameter filters the response by the specified customer ID.

    You specify input attributes in a JSON- or XML-formatted request body. For example, in the POST /V1/customers call, you must specify a request body like this:

    {
       "customer": {
           "email": "user@example.com",
           "firstname": "John",
           "lastname": "Doe"
       },
       "addresses": [
           {
               "defaultShipping": true,
               "defaultBilling": true,
               "firstname": "John",
               "lastname": "Doe",
               "region": {
                   "regionCode": "CA",
                   "region": "California",
                   "regionId": 12
               },
               "postcode": "90001",
               "street": ["Zoe Ave"],
               "city": "Los Angeles",
               "telephone": "555-000-00-00",
               "countryId": "US"
           }
       ]
    }

    This JSON-formatted request body includes a customer object with the customer email, first name, and last name, customer address information. The information in this request body is used to populate the new customer account. 

    Example: Customers Search API Request

    The following example builds a Customers Search request based on search criteria. It returns a list of customers that match given search criteria.

    Prepare Authorization, Accept and Content-Type headers to be passed to a request object. Use the Authorization token returned by the Lambda Store token service.

    $token = 'token';
    $httpHeaders = new\Zend\Http\Headers();
    $httpHeaders->addHeaders([
    'Authorization' => 'Bearer'.$token,
    'Accept' => 'appliication/json',
    'Content-Type' => 'application/json'
    ]);

    Set the headers, URI, and method to request object. Use URI /V1/customers/search and method GET values. Use the 'searchCriteria' parameter to complete the Customer Search query.

    The following example finds customers whose first name contains "ver" or whose last name contains "Costello."

    $request = new \Zend\Http\Request();
    $request->setHeaders($httpHeaders);
    $request->setUri('http://URL/rest/V1/customers/search');
    $request->setMethod(\Zend\Http\Request::METHOD_GET);



    $params = new \Zend\Stdlib\Parameters([
        'searchCriteria' => [
            'filterGroups' => [
                0 => [
                    'filters' => [
                        0 => [
                            'field' => 'firstname',
                            'value' => '%ver%',
                            'condition_type' => 'like'
                        ],
                        1 => [
                            'field' => 'lastname',
                            'value' => '%Costello%',
                            'condition_type' => 'like'
                        ]
                    ]
                ]
            ]
        ],
        'current_page' => 1,
        'page_size' => 10
    ]);

     $request->setQuery($params);

    This request returns a list of all customers in JSON format, as shown below. You can also specify XML format by changing the "Accept" header of the request.

    {
       "items": [
           {
               "id": 1,
               "group_id": 1,
               "default_billing": "1",
               "default_shipping": "1",
               "created_at": "2017-12-05 09:50:11",
               "updated_at": "2018-09-22 06:32:50",
               "created_in": "Default Store View",
               "dob": "1973-12-15",
               "email": "roni_cost@example.com",
               "firstname": "Veronica",
               "lastname": "Costello",
               "gender": 2,
               "store_id": 1,
               "website_id": 1,
               "addresses": [
                   {
                       "id": 1,
                       "customer_id": 1,
                       "region": {
                           "region_code": "MI",
                           "region": "Michigan",
                           "region_id": 33
                       },
                       "region_id": 33,
                       "country_id": "US",
                       "street": [
                           "6146 Honey Bluff Parkway"
                       ],
                       "telephone": "(555) 229-3326",
                       "postcode": "49628-7978",
                       "city": "Calder",
                       "firstname": "Veronica",
                       "lastname": "Costello",
                       "default_shipping": true,
                       "default_billing": true
                   },
                   {
                       "id": 19,
                       "customer_id": 1,
                       "region": {
                           "region_code": "London ",
                           "region": "London ",
                           "region_id": 0
                       },
                       "region_id": 0,
                       "country_id": "GB",
                       "street": [
                           "1 Studio 103 The Business Centre 61"
                       ],
                       "telephone": "1234567890",
                       "postcode": "CF24 3DG",
                       "city": "Tottenham ",
                       "firstname": "Veronica",
                       "lastname": "Costello"
                   }
               ],
               "disable_auto_group_change": 0
           }
       ],
       "search_criteria": {
           "filter_groups": [
               {
                   "filters": [
                       {
                           "field": "firstname",
                           "value": "%ver%",
                           "condition_type": "like"
                       }
                   ]
               }
           ]
       },
        "total_count": 1}

    Example: Using cURL to Retrieve a List of Products

    'cURL' is a command-line tool that lets you transmit HTTPS requests and receive responses from the command line or a shell script. It is available for Linux distributions, macOS, and Widows. To use cURL to run your REST API call, use the cURL command syntax to construct the command. For example:

    curl -s -H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXX" "https://lambdastore.com/rest/all/V1/customers/1" -o customers.json

    curl -s -H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXX" "https://lambdastore.com/rest/all/V1/orders/1" -o orders.json

    curl -s -H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXX" "https://lambdastore.com/rest/all/V1/products?searchCriteria" o products.json

    Back to TOPICS


    List of API Documentation

    Back to TOPICS