March 13th, 2015 by Adam Sandman
What are APIs and Why Should I Care?
Application Programming Interfaces (APIs) have been around for a while and they are basically a way for one application or system to interact with the functionality and features of another program. For example when you open up a mapping application and it displays restaurant reviews, more than likely it's using an API to get the data from the reviewing website to put onto the mapping one.
With the rise of mash-up applications and apps that pull data from different sources and display them in unique and novel ways, APIs have become just as important as the application itself. In fact with everyone trying to create 'ecosystems' around their products, the APIs are often more important than the application.
As mentioned, APIs have been around for a while (CORBA, COM, DCOM, RPC, MSMQ, MQ Series) but with the rise of web technologies and interconnected devices they have become a lot more important.
What is SOAP?
One of the first web service protocols was SOAP (Simple Object Access Protocol) developed by Microsoft. It allows you to send structured data (packaged as XML) from one application to another. The format and protocol is very strict and means that if you use special code libraries (e.g. JAX-WS for Java or WCF/ASMX for .NET) you basically can just write native code and the infrastructure takes care of converting the native object into SOAP XML and back again at the other end.
The advantages of SOAP are that you can just write normal C#, VB.NET, Java, etc. code and not worry about how its transmitted. However if the language you're using doesn't come with a SOAP library then writing the XML by hand is horrendous and very time consuming (i.e. don't try it at home).
When we first released Spira, we needed a way to make data import/export into the system very easy, so we added a SOAP API starting back with SpiraTest v1.2 and have steadily improved it, with the latest version (v4.2) containing many different operations on all of the aspects of the system. In addition to avoid making anyone do unnecessary work we versioned the API so that if you wrote code in 2008 against v1.2 it will still work unaltered in any way today. That backwards compatibility is something we're proud of and will be continuing in the future.
What is REST?
There are many good books on REST (also known as RESTful web services) and online resources so we won't repeat them here, but needless to say unlike SOAP which is prescriptive and can be quite heavy in terms of the size of its data packet, REST is very lightweight and very flexible. With REST You basically use standard HTTP methods (GET, POST, PUT, DELETE), HTTP headers and can send the data in any format you like. Common formats used include JavaScript Object Notation (JSON), XML and RSS/ATOM, but in theory other formats could be used just as well (CSV, delimited, etc.).
The advantages of REST are that you can use any language that has an HTTP library and nothing special needs to exist in terms of libraries. However if you are used to writing code in Java and .NET you will need to write wrapper classes to generate the JSON or XML needed. If you are using JavaScript then the advantage is that JSON is the native data storage format for objects and you can make REST requests between dynamic web applications very easily. JSON is also very compact in terms of size, which is a plus for mobile applications running on cellular data networks.
So Why Did We Add a REST API and What Does it Mean for Me?
OK So now you understand REST and SOAP, why did we add a REST API to Spira and what does it mean for the existing SOAP API and all of our existing plugins.
Well the answer to the second question, is really NOTHING. We plan on extending both our SOAP and REST APIs in future versions, with any new operation/function available to both APIs at the same time. We also plan on continuing to version the SOAP and REST APIs so that when version v4.3 and v5.0 are released, they will have new APIs that you can use, but any code written to the older v4.2 API will continue to work as before.
The only change is that you now have a choice of technology to use:
- If you are writing code in a compiled language (Java, C#) that has a strong SOAP library in place and you don't want to worry about how the data gets sent to/from Spira, then SOAP may be the easiest option since all the SOAP functions become standard functions in the library being used.
- If you are writing code in a scripting language such as JavaScript, Python, Ruby or an older language such as VBA, or you are concerned about the size/format of data being sent, then REST is for you.
So whether you are using SOAP or REST, we have an API for you...enjoy.