PHP APIs

[Korferer]

I really don't understand the point of an API. I am totally lost on this one. I have never in my life used JSON and barely touched Javascript so I'm already quite behind the curve but this was my understanding of the "purpose" of an API;

 

You have some data in a database that others might find useful so you write a script that allows people to go in and pull data from it.

 

So why aren't these APIs just built using PHP? If I have a database table of first names, last names and email-addresses, and for some reason I want other people on the internet to be able to get at that, then why don't I just write a one-page script that list them all out? Then all the user has to do is "include" it in their code, right?

 

That's probably really over-simplistic, and I am surely missing the point. There must be a point, but I cannot find a single source anywhere with an actual decent explanation of this. What am I missing?

 

You never know, perhaps you're all about to tell me that most APIs are built using PHP and what I've described is pretty much it. But everything I research leads to a dead end because they all refer to one another;

 

Example 1 - "Oh JSON is freaking awesome. I use it because it's awesome. It's awesome for work working with APIs".

 

Example 2 - "Oh, APIs, yeah, you totally have to have APIs. All you have to do is use JSON. It's awesome".

 

Not direct quotes, but close enough! Seriously, help me out. I have a lot of public data on my server and I am positive that someone can make good use of it. But how?

[Jacques1]

To be honest, I have no idea what you mean.

 

You want people to include your PHP script? How is that supposed to work? You realize that the script would run on the client's machine? Since they don't have your database, all it would do is crash. Besides that, running PHP code from some remote server is pretty much the last thing a sane administrator wants. Who knows what that script does? What if your server gets compromised and starts distributing malicious scripts?

 

So, no, this is not an option. It also makes no sense to push the data collecting logic to the client. They don't care how the data is collected. All they're interested in is the data.

 

APIs are typically based on the HTTP protocol just like web pages. The difference is that APIs are machine-friendly, while web pages are aimed at humans. A web page will deliver fancy GUIs based on HTML and CSS. On the other hand, an API will serve the data in an easy-to-parse format. JSON is fairly popular, but you might as well use XML or any other format you think makes sense.

[Korferer]

You realize that the script would run on the client's machine? Since they don't have your database, all it would do is crash.

No. I have many knowledge gaps on even the simple stuff. So if I had a website, and I wanted to include THIS page on my homepage, I couldn't just go...

 

<?php include "http://forums.phpfreaks.com/topic/289408-php-apis/"; ?>

...in my index.php and expect to see our conversation from PHP Freaks? I think I knew that a long time ago but have since forgotten. If that's right then APIs are starting to make a bit more sense to me now. FYI - I tried to run that code above and I got errors back (when I turned error reporting on)

Warning: include(): http:// wrapper is disabled in the server configuration by allow_url_include=0 in /Applications/MAMP/htdocs/index.php on line 43

Warning: include(http://forums.phpfreaks.com/topic/289408-php-apis/): failed to open stream: no suitable wrapper could be found in /Applications/MAMP/htdocs/index.php on line 43

Warning: include(): Failed opening 'http://forums.phpfreaks.com/topic/289408-php-apis/' for inclusion (include_path='.:/Applications/MAMP/bin/php/php5.5.10/lib/php') in /Applications/MAMP/htdocs/index.php on line 43

After I put out this post yesterday I did stumble upon the twitter api. Is that what most APIs are like when they are built? That's half the reason behind my original post..... Just outright confusion. I thought an API didn't have a front-end. I didn't understand the first thing about them!

[Jacques1]

In general, you can't just include files from somewhere on the Internet. The script is on somebody else's server, and you usually don't have access to the servers of other people.

 

Remote includes are a special feature which only works if you turn it on (via allow_url_include)  and have FTP access to the remote server. In that case, PHP will download the script and execute it as if it was a local file on your server.

 

This feature is very controversial, because it's obviously a major security risk. What if the script contains malicious code? Any halfway competent administrator will not even allow remote includes. It's probably best to just forget it and not regard it as a valid solution in the first place.

 

Anyway, let's hypothetically assume that you do have a remote include. In that case, you of course need the entire environment necessary to run the script. If there are queries, then you need the database. If there are references to other scripts, you need those other scripts etc. Since you most certainly don't have the database of PHP Freaks, the whole idea is bound to fail.

 

On the other hand, an API is an interface to a remote server. The server exposes a certain set of functionalities for you to use. For example, PHP Freaks could create an API to let us fetch arbitrary posts.

 

 

 

After I put out this post yesterday I did stumble upon the twitter api. Is that what most APIs are like when they are built? That's half the reason behind my original post..... Just outright confusion. I thought an API didn't have a front-end. I didn't understand the first thing about them!

 

There are no rules how an API should look like. It's entirely up to the service provider. All an API is supposed to do is accept requests (usually via HTTP) so that the user can trigger an action or get data.

 

If you think that a GUI helps people use your service, why not? 

Edited July 4, 2014 by Jacques1

[kicken]

An API basically provides a computer-friendly way for people to interact with your systems in a controlled manner.

 

Say you had a database with a list of peoples names, but in addition to names you had things like their phone numbers, addresses, etc. Maybe you want to allow other developers to query for people's names, but not any of the rest of the data. If you just provided them with a few PHP scripts that interacted with your database then what's to stop them from just changing the code to grab the rest of the details aswell? Nothing.

 

Not everyone uses PHP either. What if someone developing a desktop application using C# wanted to access your list of names? Should they have to embed PHP into their app just to run your PHP script that returns the list of names? No, they would rather just use .NET's existing http library to make a simple HTTP request and get a simple JSON response. If you want to write your end of the API in PHP then that is up to you, but your choice of language should not affect the choices of your potential end users.

 

The API sits as a gateway between your data and other people. It allows users to get data safely and in a format they can easily use regardless of what type of environment they are using.

 

The reason why JSON is commonly used with APIs is because it is an effecient and machine-friendly method of transferring data from one system to another. Most languages at this point have some means of parsing a JSON string into a native representation (or vice-versa) for further processing. JSON also contains much less bloat than something like XML for example so it saves resources such as bandwidth and processing time.

[KevinM1]

To put it in real world terms, APIs are generally used to create services for other programs/sites to use. Look at Twitter - it has an API that allows other programs/sites the ability to display and post tweets remotely. It's how all those 3rd party a Twitter apps/browser plugins work. You wouldn't expect those apps/plugins to actually contain all of Twitter's code, would you?