Posts Tagged ‘soap’

Simple Object Access Protocol (SOAP) is built on server-to-server remote procedure calls over HTTP. The data is formatted as XML; this means secure, well formatted data will be sent and received from SoftLayer’s API. This may take a little more time to set up than the REST API but it can be more scalable as you programmatically interface with it. SOAP’s ability to tunnel through existing protocols such as HTTP and innate ability to work in an object-oriented structure make it an excellent choice for interaction with the SoftLayer API.

This post gets pretty technical and detailed, so it might not appeal to our entire audience. If you’ve always wondered how to get started with SOAP API development, this post might be a good jumping-off point.

Read the full SOAP API Application Development post! »

What is SOAP?
“Simple Object Access Protocol” – SOAP is a method and format for sending XML from one server to another via HTTP. SOAP allows you to have remote database servers which supply information to power your website. The best part about SOAP is that it is universal and secure. This means that big companies like SoftLayer can open their databases for you to gather the information that you need to keep your customers up to date. This kind of complete transparency is what makes SOAP (and any other supported API) an invaluable asset to SoftLayer customers. In order to fully understand SOAP, you will need to know about markup languages, namespaces and a little about the protocols used to implement it.

Markup Languages?
The term “markup language” is derived from when teachers/editors would make corrections to a written article, using shorthand for what needed to be corrected. A markup language is just a document with a few special symbols used to separate some text as “markup;” this text can then be used by other programs to perform tasks. Markup languages are declarative programming languages, so they contain data and talk about data, but they don’t actually have instructions about what to do with the data. HTML, XML and LaTeX are all variations of markup languages.

Markup languages can be used for all kinds of different things, but the most common markup language used in web design is Hyper Text or HTML. HTML uses predetermined markup “tags” to describe data for browsers to display; it is the basic building block of all websites. SOAP uses XML to transfer data from server to server.

What is XML?
“Extensible markup language” – XML is a markup language dedicated to presenting data to different applications. Unlike HTML, XML has no dedicated markup tags; instead, you can create any type of tag you want. In XML, the tags describe and define the data that they contain. Applications can easily pull just the data that they need, no matter what is in the document. In this way an XML can be expanded without causing application errors, making it “extensible.” Due to the free form of XML tags, sometimes you want multiple tags to have the same name; this is possible with XML namespaces.

How do XML Namespaces work?
Namespaces are used to group XML elements so that parsing programs won’t confuse different elements that have the same name. Namespaces have to be defined by a “universal resource identifier” or URI; essentially, they have to be universally unique. This is why the WC3 chose to use website URLs as the standard naming convention. This can lead to some confusion when looking at XML namespaces, though. Information is not transferred to or from the websites; they don’t even have to resolve, parsing programs read the URLs as basic text strings. SOAP uses a few pre-determined namespaces to define key information, but the most important thing about SOAP is its ability to work as an RPC-type protocol.

RPC?
“Remote procedure calls” are connections created between two or more servers for the sole purpose of enacting programs or procedures on a remote server. RPCs start at the client, sending a request to the remote server with a procedure name and perameters for the procedure. The request has to be in a very strict format, that way the host server doesn’t have to know anything about the language that the client is using. SOAP makes RPCs over HTTP because it is the most accessible protocol; very few firewalls block HTTP, and SOAP makes use of headers similar to HTTP headers to provide encoding and security information.

So, What is SOAP?
In short, SOAP is a very strictly formatted XML document which uses XML namespaces to define key elements of data, sent via HTTP, in order to enact procedures on a remote server, and sometimes receive data in response to those procedures.

-Kevin

An API (application programming interface) is an interface that allows software programs to communicate with each other. The communication barrier between programs has become thinner as APIs have evolved over the recent decades, like our languages have over the years. At SoftLayer, we have plenty of opportunities to interact with many different APIs from various companies. Some of us work with a driver API, some work with SOAP, or some work with XML-RPC for some projects. If you’re our customer, I bet you can easily imagine the number of APIs we use by looking at the products and services we offer. Not only are we a large API consumer, but we also provide a great number of APIs to our own customers. It seems that the interaction between software programs evolves just like our lives.

It’s hard to survive alone in this world. We are social beings, and we need others for interaction. A software program pretty much works the same way. There is no program that is a know-it-all or do-it-all. If there were one like that, I would not have a job. Software can expand its capabilities by working with other programs just like we, as humans, help each other. APIs act as a communication tool like our languages; and, by the way, there are many dialects too.

When a program starts to interact with another through API, it can be compared to a marriage. They are stuck together. However, programs can marry many others. When two programs start to interact, one cannot change its API without the other knowing. It would be as if your wife started talking to you in Danish all of a sudden. Even a small change in an API can cause a very bad outcome. Imagine that your wife told you to throw your socks in the laundry basket and you have been following this rule for years. Can you imagine what would happen if you left your socks by the bed one day? No, it simply wouldn’t work. If you really need to change the rule, it’s time to consider a divorce, in other words, API version 2. As I mentioned, a program can have multiple partners and you can’t expect them to follow new rules all at once. Your best bet would be to write a version 2 and keep the original version for old times’ sake. Trust me, people are very hesitant when it comes to changing their routine, including me. (Why should I touch a working program just because you updated YOUR API?)

Most APIs that I have used and seen are wonderful. I have seen APIs that work like a jack-of-all-trades, trying to do everything for me, but I didn’t like it. I would not like a BLT with onions, eggs and mustard. I just wanted a B.L.T, period! I have also seen APIs that require too many prerequisite steps (invocations) to get a simple result. How many times must you get transferred until you finally get someone to help with your phone bill? Jeez!

Ok, enough of these funny comparisons. I, a biased user, have listed below what I think is a good API:

• A good API should not change often. If change is inevitable, it should give you plenty of notice and allow backward compatibility.
• A good API should explain why it couldn’t work instead of the infamous “Error: -1”.
• A good API should have good documentation, so you’re not left scratching your head.
• A good API is accessible by different platforms.
• A good API should be stable.
• A good API should be simple and comprehensive. It should do what it says it does and it should do it well. Prefer “powerOn()” over “powerOnWhenIdleAndStartServices()”.

A good API implies the readiness of communication with other programs and other companies. It will broaden opportunities for your programs and organization to work with others, just like a person with good communication skills has a better chance of fitting in our society.

Recently, as you know, SoftLayer released the new API version 3. We have all been working very hard on it, and we’ve been completely immersed in it for weeks (months, for some of us). This means that, for the developers, we’ve been living and breathing API code for quite some time now. The time came to release the API, and as many of you know, it was a smashing success. However, we were lacking in examples for its use. Sure, we all had examples coming out our ears since the customer portal itself uses the API, but those were written by the same developers that developed the API itself, and therefore were still written from an insider’s perspective.

So a call went out for examples. Many people jumped on the list, offering to write examples in a variety of languages. I thought I would tackle writing an API usage example in Perl. Perl, for those of you unfamiliar, is an infamous programming language. Flexible, confusing, fantastic and horrifying, it is the very embodiment of both “quick and dirty” and “elegance.” It is well loved and well loathed in equal measure by the programming community. Nevertheless, I have some experience with Perl, and I decided to give it a try.

I will attempt to describe my thought process as I developed the small applications (which you should be able to locate shortly in the SLDN documentation wiki) throughout the work day.

9am: “Wow, I really don’t remember as much Perl as I thought. This may be difficult.”
10am: “I need to install SOAP::Lite, that shouldn’t be hard.”
11am: “Where the heck are they hiding SOAP::Lite? There are articles about it everywhere, but I can’t actually find it or get it installed!”
12pm: “Ok, got SOAP::Lite installed, and my first test application works perfectly! Things are going to be ok! Wait…what’s all this about authentication headers?”
1pm: “What have I done to deserve this? Why can’t I pass my user information through to the API?”
2pm: “Aha! Another developer just wandered by and pointed out that I’ve been misspelling ‘authentication’ for 2 hours! Back on track, baby!” (Side note: another “feature” of Perl is how it never complains when you use variables that don’t exist, it just assumes you never meant to type that. Of course, you could tell it to complain, but I forgot about that feature because I haven’t used Perl in 4 years.)
3pm: I finally get example #1 working. It queries the API and shows a list of the hardware on your account.
3:30pm: Example #2 working, this shows the details for a single server, including datacenter and operating system
4pm: Combining examples #1 and #2, the third example shows all hardware on your account, plus the installed OS and datacenter, in a handy grid right on the command line. Success! I put Perl away, hopefully for another 4 years.

The whole experience, though, really gave me an insight into how fantastically awesome the API is. I was looking at it from an outsider’s perspective. I was confused as to how everything worked, I was working with an unfamiliar language, and I was browsing through the API looking for anything that looked “cool and/or useful.” Getting a list of all my account’s hardware to show up in a custom built application that I wrote as if I knew nothing about the API was a great feeling. It showed that not only was the API perfectly suited to the tasks we expected of it, but even a novice developer could, with a little effort, make an API application like mine. Expanding on it to show more and more information, and all the possibilities that it opened up in my mind made me realize how useful this API is that we made. It’s not just something that a small percentage of our customers will be using. It’s something that is truly revolutionary, and that all clients can take advantage of. I’m assuming, of course, that all clients have at least rudimentary skill in at least one programming language, but given the level of success everyone has had with our other offerings, I can assume that assumption is accurate.

If you have been thinking recently “look at all the noise they’ve been making about this ‘API’ nonsense,” I highly recommend dusting off an old programming book and at least looking at it once. Think of all the possibilities, all the custom reports that you can make for yourself, all the data that we have provided right at your fingertips to assemble in any way you wish. We try our best to make the portal useful to every customer, but we know that you can’t please all the people all the time. But with the API, we may do just that. If you’re the kind of customer that is only interested in outbound bandwidth by domain, write an API script that displays just that! If you want to know the current number of connections and CPU temperature of your load balanced servers, get that data and show it! The possibilities are endless, and we’re improving the API all the time.

-Daniel