API Basics - If you are new to the Spire API - Start here!
S
Spire A Developer
started a topic
almost 3 years ago
If you are new to the Spire API, it's useful to have a platform from which to assemble and try examples. People all have different learning strategies. This document tries to approach the API by providing a means to execute examples, and see their results. This can be challenging, because API use generally involves some degree of development effort, and the tools, languages and frameworks vary in complexity and there are many of them. The goal here is to provide some level ground from which to build knowledge and facility with the API.
This example uses a free application called CURL. It's a generically used, freely available command line application. With it, you can do everything that the Spire API browser (the web based way of accessing the Spire API) can do (and a lot of things it cannot). For reference, Spire QA uses this tool, and many API examples in order to build companies and setup test data for test automation. It's fast, relatively easy to use, and it removes the complications of discussing the plumbing of other tool chains and languages. Even if your goal is to write a complex, object oriented, compiled application this topic is a good place to start. All the examples in this topic and in the rest of the forum can be tested and experimented with using Curl.
Note that a prerequisite before beginning is that the Spire application and server be installed, and that there be a known url where you can access a Spire company. Ideally, you can login to this company and work back and forth between the Spire desktop user interface, and the API. This is really helpful for validating results (e.g. Did the part number I tried to created get created in the expected way). It's also important to mention the that Spire API honors the same constraints as the Spire user. If a user cannot, for example, access General Ledger resources, they will be blocked in the Spire API as well.
* Be aware that you can effect data with the Spire API, and this extends all the way up to and including deleting an existing company. Use care, and make sure you have complete backups before proceeding.
It's a small command line tool, and you don't need to worry about it interfering with anything. Attached is a batch file that;
1 - Deletes a sample company (TestCo) and then creates a company
2 - Adds two inventory items
3 - Adds a vendor and customer
4 - Adds a sales order
5 - Invoices the sales order
6 - Starts and logs on the Spire
As mentioned earlier, each of the actions executed in the batch file are used extensively by Spire QA. If your initial attempt to run the example does not work, keep digging. Development is a process of failing many times, and succeeding through trial and error. A hint - if parts of the batch file don't appear to work for you, you can launch a command line session and run these commands one by one. The advantage of doing this is that you get to see the results as they occur.
"curl --help" from the command line explains all the command line switches used in this example.
Your URL's will vary relative to the example, as will your user ID and password.
"localhost" basically means "this machine". You can replace the Url with your ip address, a server name or the allocated Spire hostname. A hint here - If you logon to Spire desktop and choose "Tools, Spire Server Administration" you will be re-directed to the correct Url.
Delimiters when working with Curl can be a little tricky, and they are easy to get wrong. You'll notice that things like paths are structured differently than what you often see in Windows environments. Curl is a cross platform tool, which explains this difference. Pay attention to the use of quotes and slashes.
The "-o" command is really useful, because you can have CURL write out responses to files and review them. On line 32, there is an example of this. When successful, CURL returns the response which includes the invoice number Spire assigned (or an error if the command was unsuccessful).
A couple of key concepts
Rest API's use a small number of HTTP verbs. POST is generally used on a collection in order to create a new resource. PUT is generally used to update or change an existing resource. You normally use a PUT verb on an endpoint (rather than a collection).
Collections are are expressed to the Spire API as groups of records. The following is a collection;
Notice the the presence or absence of a forward slash determines whether a url is addresses as a collection or and endpoint. In the above example, the url points to a specific part number with the ID of "1".
Structuring Json can be a challenge when you are doing it by hand. Note that generally in larger applications you will use tools to help you with this. Ultimately some kind of object model is often build to map your data to Spire expectations. That is beyond the scope of this discussion, but it's useful to be aware of this.
Additional thoughts
There are a number of different tools that perform the same function as Curl (Postman for example). Fidler is another example of a similar tool. Curl happens to have the advantage of being straight forward, easy to automate and setup is very minimal. Use the tools that suits you best.
There are many examples you can find around the internet, and Curl is widely used when you want to branch out.
It makes sense to get this example working before you move on to trying to adapt this to customer data, or your own. All the principles here apply to whatever language and frameworks developers subsequently decide to use.
There are a number of other examples in this forum that should be easily adapted to the example provided here.
Spire A Developer
If you are new to the Spire API, it's useful to have a platform from which to assemble and try examples. People all have different learning strategies. This document tries to approach the API by providing a means to execute examples, and see their results. This can be challenging, because API use generally involves some degree of development effort, and the tools, languages and frameworks vary in complexity and there are many of them. The goal here is to provide some level ground from which to build knowledge and facility with the API.
This example uses a free application called CURL. It's a generically used, freely available command line application. With it, you can do everything that the Spire API browser (the web based way of accessing the Spire API) can do (and a lot of things it cannot). For reference, Spire QA uses this tool, and many API examples in order to build companies and setup test data for test automation. It's fast, relatively easy to use, and it removes the complications of discussing the plumbing of other tool chains and languages. Even if your goal is to write a complex, object oriented, compiled application this topic is a good place to start. All the examples in this topic and in the rest of the forum can be tested and experimented with using Curl.
Note that a prerequisite before beginning is that the Spire application and server be installed, and that there be a known url where you can access a Spire company. Ideally, you can login to this company and work back and forth between the Spire desktop user interface, and the API. This is really helpful for validating results (e.g. Did the part number I tried to created get created in the expected way). It's also important to mention the that Spire API honors the same constraints as the Spire user. If a user cannot, for example, access General Ledger resources, they will be blocked in the Spire API as well.
* Be aware that you can effect data with the Spire API, and this extends all the way up to and including deleting an existing company. Use care, and make sure you have complete backups before proceeding.
"localhost" basically means "this machine". You can replace the Url with your ip address, a server name or the allocated Spire hostname. A hint here - If you logon to Spire desktop and choose "Tools, Spire Server Administration" you will be re-directed to the correct Url.
A couple of key concepts
Rest API's use a small number of HTTP verbs. POST is generally used on a collection in order to create a new resource. PUT is generally used to update or change an existing resource. You normally use a PUT verb on an endpoint (rather than a collection).
Collections are are expressed to the Spire API as groups of records. The following is a collection;
Endpoints represent a specific resource. The following is an endpoint;
Notice the the presence or absence of a forward slash determines whether a url is addresses as a collection or and endpoint. In the above example, the url points to a specific part number with the ID of "1".
Structuring Json can be a challenge when you are doing it by hand. Note that generally in larger applications you will use tools to help you with this. Ultimately some kind of object model is often build to map your data to Spire expectations. That is beyond the scope of this discussion, but it's useful to be aware of this.
Additional thoughts
There are a number of other examples in this forum that should be easily adapted to the example provided here.
4 people like this idea