Question

What I want and have

I’m willing to create an API, I already know what does an API stands for.
I use PHP as a server side language.

However I don’t really understand how an API works from scratch, and how can I enable users to use my API after I created it.

What I think and know

Well right now I think that with an API I enable developers to reach my database and request queries. But then why should I create a full language for it? Why can’t they use PHP or any other server side language?

As I saw, companies who crates API’s for their site, they require a registration to give to developers an API KEY. Does the developers log in to database trough this API KEY? And if yes, then why they don’t have a password too? If I know somebody’s API KEY I can use it or what?

And as I read/heard XML is related somehow to API’s, but why and how?

Also please consider in your answers that I don’t want to use any frameworks or something like that, I want to make it in scratch so I want to understand how it works from A to Z.

Answer 1

An API is really just methods that you publicly expose. Say, for example, you have a blog site. You want your members to be able to post a blog entry without actually coming to your site – logging in, filling out a form, etc..
Perhaps they want to create an Android/IPhone app to post to your cool blog site. You can allow them to do that.

Create an API for this:

    <?php
        function createBlogEntry(memberEmailAddress, memberPassWord, BlogTitle, BlogBody)
        {

           //Here you would usually call an internal (or not publicly exposed) method that
           //contains the actual logic to insert. Like Jim's answer states, you just want 
           //people to be able to performan action in your system, you don't want them to see HOW you do it.

          encapsulatedBlogCreation(memberEmailAddress, memberPassWord, BlogTitle, BlogBody);  


           //This is where API's get tricky. I need to return to the user the result of
           // the save so that my user knows what happens. In my API documentation, I 
           //tellthe user 0 = Created Successfully. If this is a READ operation
           //just return the result. Most modern programming languages also have
           //a way to capture an HTTP response - so dealing with the return is their responsibility

            return 0;
        }
 ?>

A couple things:

• In my API, I didn’t need a developer Key, I allowed the user to pass in their login credentials. An API key does the same thing, it uniquely identifies a request and links it to a user in the system.
• This API doesn’t use XML. This is about as simple as an api gets. This can be called by sending an HTTP request which can be done with any modern programming language. Say I put the above code in a file called blog.php and put it in the root of my blogsite. I would call it like:

*http://myblogsite.com/blog.php?memberEmailAddress=[e-mail]&memberPassWord=myPass&BlogTitle=Title-of-post&BlogBody=the_blog_post_is_here*

One thing you need to understand, is that there has to be a need for an API. You can expose a method to create a blog entry, but if no one knows about it or uses it – it’s worthless. API’s need to be documented, advertised, and provide a benefit to potential users.