API, REST, SOAP, XML-RPC, WTF?!?!

[eluser]slowgary[/eluser]
Hi guys,

I'm considering writing an API for a project I'll be working on soon, but I'm not 100% sure of what an API even IS or if it's the best route. I hope you can help.

I've used the USPS Webtools API which allows me to send a chunk of XML to a certain URL and receive a chunk of XML in response. I do this with cURL and use SimpleXML to access the return object. Everything works and I'm happy ;-p That's the only API I've ever used , unless jQuery or CI are considered APIs as I've seen threads about the "CodeIgniter API Doc" which confuses me because I always thought of an API as a sort of black box where you could pass some GETs or POSTs in and you could receive some back. If anyone could add some clarification to my confusion I would greatly appreciate it.

So as far as writing my own "black box", I'll be putting together a site that sells custom made products with a very difficult pricing model. The company has previously had several sites made and they've alway been very spaghetti coded and can barely get the pricing right, additionally the UI is TERRIBLE and so inefficient that most customers end up calling to get a quote or place orders by phone. Since each site has re-implemented the logic for pricing, my idea for a solution is to abstract the pricing logic as an API that could be used in the future so that this problem will never have to be tackled again. Even if the next site ends up on a windows server in ASP.NET, the site could query my CI/Linux/PHP/MySQL based pricing API. Does this sound like a smart approach?

Can anyone also shed some light on all of the acronyms surrounding this topic? I know what the letters stand for, and I've done a lot of searching on the topic, but all I ever find are articles talking about 'Web Services' or 'a way to pass routines and data structures'. What my brain needs is an explanation of what each of these acronyms actually DOES as it relates to the code. So if I were to explain to someone how the USPS Webtools API worked, I would tell them: "You can build a string of XML tags, send it to this URL with cURL, and access the resulting data like this...".

Do the differences between REST, SOAP, XML-RPC have anything to do with the type of data that's exchanged? Are these terms synonymous? I've looked at the XML-RPC class in the user guide but I don't understand it, and I tend to shy away from things I don't understand. The class doesn't seem to mention anything about the order of parameters for a call - are they required in a fixed order as a function call is? I like the XML approach as it doesn't matter what order the data is in, each piece has it's own descriptive name.

Can anyone tell me what type of API the USPS Webtools API is? Where do I go from here?

Please help. And thank you.

[eluser]Yorick Peterse[/eluser]
Rest is the way to go : http://en.wikipedia.org/wiki/Representat...e_Transfer

[eluser]Dam1an[/eluser]
Yorick, I'm suprised you didn't take this as a chance to plug your REST library, oh wait, it's not finished yet

[eluser]Phil Sturgeon[/eluser]
I have had a look at a few of these systems briefly but mainly REST. I have been converting some legacy data transfer systems to use REST at work and from what I hear from colleagues who have tried the alternatives REST is a speedy, light and flexible superior.

XML-RPC is old and much slower. XML is always going to be slower than other methods as the syntax is the largest, however there are other factors causing the speed issues.

SOAP is heavily type-based which works well when PHP is interacting with other systems that enforce types more (VB, C++, Java, etc). At work we handle lots of statistics and financial data so obviously type-based is good for much of it.

REST to me seems much more flexible. From what I understand you pass it a format type, a method suggesting what you wish to do (GET, POST, PUT, DELETE) and some basic prameters via URL or HTTP headers. This allows you to return data in any format you like based on the request you send so it works with almost any system you can imagine.

Seeing as my REST imlementstion IS finished, I can go ahead and plug away. Sorry Yorick. ;-P

[eluser]slowgary[/eluser]
Thanks for joining the party guys, but I still feel left in the dark.

I don't understand what all these acronyms MEAN. Should I just not worry about it and create a controller that receives post variables and a response to the page? Then sites that rely on the API could just cURL some post data to the controller and scrape the response. Does that make sense? If so, what type of API is that?

Sorry for being extremely noobish, but there's only one way to get out of noob status - and that's bootcamp. Since I don't really want to go to bootcamp, I choose to eternally ask stupid questions. Thanks again.

[eluser]Phil Sturgeon[/eluser]
I had hoped someone with a bit more knowledge on the subject would jump in to clear things up a little, but you might be in for a wait.

When you say "Should I just not worry about it and create a controller that receives post variables and a response to the page? Then sites that rely on the API could just cURL some post data to the controller and scrape the response.", that is all any of these API "methodlogies" use. They just do it in a certain way with certain suggestions.

In much the same way as CodeIgniter's MVC patterns can be followed or ignored, so can these methodoligies. At work we use what we call a REST API, but really it is a mere GET based API. Other than the fact we can make oour URL requests in a certain way, not much sets our REST server apart from any other PHP outputted XML, JSON, etc.

If you basically just want to server up XML to other pages, you can do that with basic CodeIgniter and XML, or take a look at the REST controller I posted above which should show you how to make a very simple XML API. You can use the example controller and all the formats default to XML so you can't go wrong.

I will have a REST client API finished which will accept output created by your REST controllers (or any other REST API). Essentially, my REST client is a tarted up cURL wrapper that handles format convertion and MIME types, so again, you are on the right lines.

[eluser]jedd[/eluser]
Hey slowgary, not sure if I can add any clarity to the conversation, but at the very least you can feel better knowing that someone else is sharing your cluelessness.

As I understand it - and I am by a long way no expert in this field - SOAP is almost deprecated, at least in the realms we're likely to move in, by its sheer complexity and weight.

XML bundling of data - or JSON if you prefer something ostensibly simpler - is a good way, by my understanding of both it and the description you have provided for what you are aiming to achieve - and is probably your best way forward.

REST is a way of communicating where the entire state of the current transaction is transferred through a URL (or equivalent). Most REST implementations I've seen have usually been half-arsed (intentionally or otherwise - Facebook is a prime example of the first type). I can see the engineering elegance that REST is aiming to achieve, but ultimately I can't see the point (and before anyone pops in with a '-' isn't a hexadecimal digit style counter - I can see the point that is usually proferred as an explanation, but there are other, simpler technologies that can achieve the same result).

[eluser]slowgary[/eluser]
Phil, Jedd - I appreciate the clarification. I've been googling as much as possible to understand more, but as I stated before, much of the information is a bunch of jargon with very little actual examples to illustrate.

I do think I understand enough to get by (although it's always nice to know which acronyms you can add to your resume), and I see that just like a lot of things, these are just ideas about how to get the job accomplished. In the end, whatever I feel most comfortable with as a solution will be what I do.

As for specifics, I'm scratching SOAP off my list as I'd prefer pure XML to the SOAP syntax. For all I know, SOAP syntax is pure XML, but as stated earlier - I tend to shy away from technologies that look foreign to me and the examples I've seen of SOAP objects look a lot uglier than a clean hierarchy of XML. That being said, I think as an input format I might skip both of those in favor of a lighter and easier set of POST variables.

I don't really get the REST idea using strictly the URL because of the limited URL length. Plus, CI style parameters makes it slightly more difficult to determine the pairing of key/value. Additionally, doesn't this method require parameters to be in a specific order?

Acronyms aside, I think I'll stick with regular old POST variables as input, and offer JSON and XML as output. I think this would be the best approach for me as I could cURL the API from other PHP scripts and access the response through a SimpleXML object, and I could call the API through AJAX and get the response as native JS.

Does this sound like a sound approach?

Also (slightly off topic) - if I implemented a simple username/password to authenticate users of the API, unauthorized users could simply view the javascript source and snatch credentials. Is there a better approach to securing usage of the API, or are most APIs open by nature?

Thanks again for all your replies, I feel like I've really learned something today.

[eluser]Phil Sturgeon[/eluser]
Let me clean up a few things about REST.

REST is not only set via the URL, it is meant to be controlled with the HTTP header request which is how the web is meant to work. This can be done with my REST controller / REST client library easily enough.

Using cURL you can send POST variables to REST just like anything else.

REST parameters in the URL using default CodeIgniter would need to be sent in order, but so would they if you use ANY methodology in CodeIgniter. That is just how CodeIgniter's URI parameters work by default. My REST controller uses $this->uri->uri_to_assoc() to make assosiative URL arrays. Eg:

http://example.com/index.php/controller/...am2/value2 etc. They can be in any order and be entirely optional.

Take a look at the links in my code. The example controller will show you exactly how to get it working.

[eluser]Colin Williams[/eluser]
REST is about 2 things, Resources and Verbs. Resources are your application objects: Users, sessions, searches, projects, nodes, posts, etc. These are represented by, wait for it, URIs, Uniform Resource Indicators. Then, the Verbs are what you do with those resources. There are 4: GET, POST, PUT, and DELETE. These are communicated via the REQUEST_METHOD HTTP header.

PUT http://www.example.com/user/1 (Update and save user #1's info)
DELETE http://www.example.com/project/455/todo/3555 (Delete todo #3555)
GET http://www.example.com/session/user/69 (Retrieve user #69's session to determine if they are logged in or not)
POST http://www.example.com/node (Create a new node)

REST unfortunately cannot be used through the browser because browsers only support GET and POST, but nothing stops two servers from having RESTful APIs (as mentioned, using cURL in PHP).

API just means Application Programming Interface. It is mainly the language you use to interact between applications or within applications. So, if you have Models in your application, your Model has an API. It doesn't just mean communication between your site and Flickr or Google or Facebook, etc., it's specifically how communication is designed to happen.

Hope that clears a bit up.