This example uses the Spire API to create a customer, read the customer information, update the customer details with changes and finally delete the customer from the Spire customer list.   The Spire API is based on REST.   This is a industry standard approach for communicating with a server, asking the server to perform actions, and validating the results of those actions.   A server can be your local machine, the server on your LAN, or a server running somewhere on the internet.


The key concepts demonstrated here are that to add an item, you POST to a collection.   To read a group of customers, you READ from a collection.   To read a specific customers attributes you READ from a specific customers endpoint.   A customer endpoint is expressed as the customers internal ID.   To update a specific customer, you reference the customer end point and use a PUT command.   Finally to DELETE, you reference the specific customer on it's respective endpoint.


It is very helpful to use the built in Spire API browser to visualize collections and endpoints.  The Spire API browse is installed as part of the Spire application.   No additional software is required.


To navigate to a company directly, and see all available collections enter the following in your browser (we are using Chrome in this example)


https://localhost:10880/api/v2/companies/SuperCo/


A few things are important to note.


1 - localhost:10880 refers to you local machine.   This can be replaced by the name of your Spire server, or you may also use your assigned Spire hostname.

2 - There are two versions of the API.   We recommend at present that v2 be used

3 - You specify the database name of your company where SuperCo is entered in the example

4 - The final trailing slash (/) is important.   Collections are generally ended with a (/) whereas endpoints are not

5 - Using the API browser, you will be prompted with the requirement to authenticate (user name and password).  The users capabilities are mirrored in the API.  You may only perform actions the user, logged into Spire desktop, is allowed to perform.


Add a customer


To add a customer, send the following Json to the customer collection using a POST action.


{
  "customerNo": "KEVINSMITH",
  "name": "Smith Incorporated",
  "address": {
    "line1": "123 Main Street",
    "line2": "",
    "line3": "",
    "line4": "",
    "city": "Burlington",
    "postalCode": "L7L3G1",
    "provState": "ON",
    "country": "CAN",
    "phone": {
      "number": "9058021007",
      "format": 1
    }
  }
}


Use the customer collection;


https://localhost:10880/api/v2/companies/SuperCo/customers/


The action used to add the customer is a POST.   You can perform this action using the API browser.



If the POST action is successful, the customer will have been added to the Spire company database and will be accessible via the Spire desktop application;



Note the the API browser often provides useful information if there is an error trying to add the customers.



Read a customer


The Spire API browser automatically read customer information as you navigate through the collection, and on to particular endpoints.  Notice in the following example, that the Spire API browser has performed a GET on the endpoint;


https://localhost:10880/api/v2/companies/SuperCo/customers/1





This returns the attributes of the selected customer.


Update a customer


To update a customer, you identify the specific customer, via it's endpoint. 


https://localhost:10880/api/v2/companies/SuperCo/customers/1


You can use the Spire API browser to update a customer as well.   Navigate to the endpoint above, scroll to the bottom of the screen and paste in the following Json.   


{
  "address": {
    "line1": "556 West Mall",
    "line2": "Third floor",
    "line3": "Suite 48",
    "line4": "",
    "city": "Mississauga",
    "postalCode": "N7L3G7",
    "provState": "ON",
    "country": "CAN",
    "phone": {
      "number": "4167270334",
      "format": 1
    }
  }
}


Notice that, since you have already identified the customer by navigating to their endpoint, it is not necessary to specify the customer number or ID.   


Updating a customer requires use of the PUT command, which the Spire API browser provides;



Delete a customer 


A customer record is deleted by referencing the customer endpoint.   To remove the customer, send the DELETE command.