SitePoint Sponsor

User Tag List

Results 1 to 13 of 13
  1. #1
    SitePoint Enthusiast PHP_Adam's Avatar
    Join Date
    Jan 2009
    Location
    West Yorkshire, UK
    Posts
    92
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)

    XML API - Best Practace

    I was first thinking about using PHP Soap but found that most API's are using XML. So that's probably the best road to go down.

    I have two and maybe three sets of data that I wish to release to customers via a API. I don't want to release these if they are unusable.
    Ive not really used many API's except limited use of audioscrobbler.

    So im looking for articles, tutorials or advice regarding best practice in developing API's?
    .. Such as displaying errors
    .. Efficient API Key validation / usage

    Google fails to return much, most of my knowledge has come from looking at others api.
    Last edited by PHP_Adam; Jul 18, 2009 at 09:48.

  2. #2
    SitePoint Wizard silver trophy kyberfabrikken's Avatar
    Join Date
    Jun 2004
    Location
    Copenhagen, Denmark
    Posts
    6,157
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by PHP_Adam View Post
    I was first thinking about using PHP Soap but found that most API's are using XML.
    SOAP is based heavily on XML.

  3. #3
    SitePoint Enthusiast PHP_Adam's Avatar
    Join Date
    Jan 2009
    Location
    West Yorkshire, UK
    Posts
    92
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by kyberfabrikken View Post
    SOAP is based heavily on XML.
    Yer, Soap is tied to XML because all messages sent to and from a SOAP server to Soap Client are sent in a SOAP envelope that is an xml wrapper, but they call it WSDL
    Its mainly OOP based which is not a strong point of mine.

    Most API's just use raw XML requests and raw output ive found. Presumably better to stick with convention, not seen many services at all useing SOAP.

  4. #4
    SitePoint Wizard silver trophy kyberfabrikken's Avatar
    Join Date
    Jun 2004
    Location
    Copenhagen, Denmark
    Posts
    6,157
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    I wouldn't suggest SOAP either; It's a nightmare to work with. Especially in a dynamically typed language with poor library support (Eg. anything that isn't Java or .net).

    If you have free hands, I would suggest either xml-rpc or a rest-style service using either json or xml as the content-type.

    Here are a few primers, that can help you with building a rest style service:
    http://www.infoq.com/articles/webber-rest-workflow
    http://blog.feedly.com/2009/05/06/be...-web-services/

  5. #5
    SitePoint Enthusiast PHP_Adam's Avatar
    Join Date
    Jan 2009
    Location
    West Yorkshire, UK
    Posts
    92
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Thank you kyberfabrikken, Those links came in very useful and changed the way I was going to approch it. I have compleated V1 of the API its just searching and selecting data at the moment. Will move on to insert and update later.

    Just a note to anyone else making an API.
    SimpleXML is key.
    PHP Code:
    //Conditional AND in where for complex api searches
    if(isset($_GET["lyric"])){
            if(isset(
    $WHERE)){ $WHERE .= ' AND '; }
            
    $WHERE .= "(`lyric_text` like('%" $_GET["lyric"] . "%')) or (`lyric_text` like('%" $_GET["lyric"] . "%'))";

    PHP Code:
    //Useful for outputting data, that does not conflict with xml spec
    htmlspecialchars(utf8_encode($data)); 

  6. #6
    SitePoint Wizard silver trophy kyberfabrikken's Avatar
    Join Date
    Jun 2004
    Location
    Copenhagen, Denmark
    Posts
    6,157
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by PHP_Adam View Post
    PHP Code:
    //Conditional AND in where for complex api searches
    if(isset($_GET["lyric"])){
            if(isset(
    $WHERE)){ $WHERE .= ' AND '; }
            
    $WHERE .= "(`lyric_text` like('%" $_GET["lyric"] . "%')) or (`lyric_text` like('%" $_GET["lyric"] . "%'))";

    Remember to escape strings if you embed them in sql. In this case, your code should read:
    PHP Code:
    //Conditional AND in where for complex api searches
    if(isset($_GET["lyric"])){
            if(isset(
    $WHERE)){ $WHERE .= ' AND '; }
            
    $WHERE .= "(`lyric_text` like('%" mysql_real_escape_string($_GET["lyric"]= . "%')) or (`lyric_text` like('%" mysql_real_escape_string($_GET["lyric"]) . "%'))";


  7. #7
    PHP/Rails Developer Czaries's Avatar
    Join Date
    May 2004
    Location
    Central USA
    Posts
    806
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Please do the web a favor and don't use SOAP. Quite the misnomer. It's anything BUT simple. Just use a simple XML API. SOAP really is a nightmare to work with.

  8. #8
    SitePoint Guru bronze trophy TomB's Avatar
    Join Date
    Oct 2005
    Location
    Milton Keynes, UK
    Posts
    989
    Mentioned
    9 Post(s)
    Tagged
    2 Thread(s)
    Yeah, soap makes simple tasks overly complicated.

    One thing I have been doing for complex AJAX applications is requesting an XML document, keeping it in the browsers memory and posting it back to the server as XML with changes.

  9. #9
    SitePoint Guru
    Join Date
    Feb 2002
    Posts
    625
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    You guys care to eloborate on why you think SOAP makes things complex, or is a nightmare to work with? (I have been using and creating SOAP web services for years, and not once found it to be a big hassle, let alone a nightmare to work with, quite the contrary, the companies I have worked for had quite the heterogeneous system landscapes, including but not limited to Oracle, MS-SQL, PostgreSQL, MySQL, SAP and Axapta, and let me tell you I was quite the happy man knowing I could exchange data with those systems using something as (IMHO) simple as SOAP.) I have also heavily used XML-RPC, but SOAP wins over XML-RPC by a longshot. Also I think today it is easier then ever to use SOAP, what with ZF.

    So what have I missed?

  10. #10
    SitePoint Zealot Amenthes's Avatar
    Join Date
    Oct 2006
    Location
    Bucharest, Romania
    Posts
    143
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by datune View Post
    You guys care to eloborate on why you think SOAP makes things complex, or is a nightmare to work with? (I have been using and creating SOAP web services for years, and not once found it to be a big hassle, let alone a nightmare to work with, quite the contrary, the companies I have worked for had quite the heterogeneous system landscapes, including but not limited to Oracle, MS-SQL, PostgreSQL, MySQL, SAP and Axapta, and let me tell you I was quite the happy man knowing I could exchange data with those systems using something as (IMHO) simple as SOAP.) I have also heavily used XML-RPC, but SOAP wins over XML-RPC by a longshot. Also I think today it is easier then ever to use SOAP, what with ZF.

    So what have I missed?
    I have two problems with SOAP, both of which I have encountered in my work.

    1. I hate web services that use SOAP but have no WSDL.
    2. I hate even more web services that use SOAP and have a WSDL in which
      every type is declared as anyType. Every attempt at automating that is
      useless. I asked the guys why did they choose to have all types as anyType.
      They said because they wanted their specification to be open for extension
      in the future and not cause backwards incompatibilities.


    I've tried Amazon's SOAP/WSDL for a bit and looks OK, but that was just for
    fun late in the night. At my day job, having to generate or write classes for
    almost one hundred XSD files is a nightmare. There's no reason in using SOAP
    or WSDL if you don't fully automate it.

    SOAP is nice, for languages like Java and C#, or even PHP, as long as it allows
    automatic discovery of the services, otherwise... I see no reason to clutter
    my XML structures with useless Head and Body elements, namespaces, target
    namespaces or the like.
    I'm under construction | http://igstan.ro/

  11. #11
    PHP/Rails Developer Czaries's Avatar
    Join Date
    May 2004
    Location
    Central USA
    Posts
    806
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    The last SOAP API I had to interact with had an incomplete WSDL file and a bunch of custom data types, so I had to hand write over 30 classes by trial and error just to call one single function. It took the entire day to get working consistently well. If it was XML or JSON I would have been done in 10 minutes. That's what I call a complete nightmare.

  12. #12
    SitePoint Guru
    Join Date
    Feb 2002
    Posts
    625
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by Czaries View Post
    The last SOAP API I had to interact with had an incomplete WSDL file and a bunch of custom data types, so I had to hand write over 30 classes by trial and error just to call one single function. It took the entire day to get working consistently well. If it was XML or JSON I would have been done in 10 minutes. That's what I call a complete nightmare.
    And based on this you decided to spread the word that SOAP is bad? Mkay ;-) Your example jut goes to show that there are way to many incompetent people out there working with things that they know next to nothing about...

  13. #13
    SitePoint Wizard silver trophy kyberfabrikken's Avatar
    Join Date
    Jun 2004
    Location
    Copenhagen, Denmark
    Posts
    6,157
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by datune View Post
    You guys care to eloborate on why you think SOAP makes things complex, or is a nightmare to work with?
    There are two big problems with SOAP. The first is the mere complexity of the protocol. This means the only sane way to use SOAP is through an opaque abstraction layer. And because of the complexity, many languages (PHP is no exception) simply don't have libraries available that supports the complete standard. And, when things go bad, there is no proper way to debug it.

    The other issue I have with SOAP is that it's designed around the idea of a static type system. I'm sure this makes sense in Java and C#, which are statically typed languages, but in a dynamically typed language it is a huge load of cruft for no gain at all. Your style of programming may influence how heavy this argument weights, since PHP is a bit of a hybrid in this sense. For me, it's really annoying. To top it off, the very type system is often a source of errors, when one side of the connection has a more relaxed implementation than the other. It's quite common for the service to violate its own WSDL/XSD. Yes, that's the fault of the user - not the protocol per se - but that's a rather academical defence to make, when you're on the receiving end (literally and metaphorically).


Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •