
APIs – a beginners’ guide - benhowdle89
http://benhowdle.im/2013/01/24/apis/
======
tikhonj
This seems to jump into web-based APIs without mentioning it. An API _does
not_ have to be web based: it could be a set of classes, or methods, or
modules or functions to be used from a language directly.

Web services, of course, tend to have web-based APIs. But that's a subset of
_all_ APIs.

Since this article seems aimed at beginners, I think it's an important
distinction to note. You would not want beginners to think that APIs are
_always_ web-based because then they'll be confused by things like WebGL,
which is also an API but _does not_ involve web requests or AJAX.

~~~
blowski
From my experience of explaining APIs, most people don't understand the
distinction between the web and software, let alone the difference between a
web-based API and a software one. If a user knew what WebGL actually is, I
would guess that they already know what an API is.

------
RTigger
As I noted in the article's comments, I'm pretty sure you can't just add
"dataType:jsonp" and have it automagically bypass all the cross-domain
security restrictions.

What actually happens is jQuery appends something like
"callback=some_random_function" to the end of the querystring when it makes
the request, and then the server is supposed to return you the standard data,
wrapped in a function definition with the same name. jQuery then automatically
executes the function, making the json data available.

Some servers require a specific function name, which can be specified as an
ajax option using "jsonpCallback: functionName". All this effectively does is
uses a specific function name instead of a randomly generated one, so that it
matches up with the function returned from the server in the response.

------
edparry
Thanks for this -- I think I'm your target audience here. CS student, entirely
aware _of_ APIs, but not a clue how to interact with them. Yet I now have
tweets flying left, right and center. So thanks!

~~~
benhowdle89
Awesome, glad you liked it!

------
seivan
For restful HTTP...

I like to keep my API strict resources, and nest them if necessary. Also avoid
using more than 4-5 verbs per resource.
<https://github.com/seivan/DocumentationExample>

POST, PUT, GET (member), GET (collection) and DELETE on a resource and nothing
more. If a resource needs different kinds of colletions (say a filter) I'd use
query parameters.

This makes working with API's as a consumer so much easier, especially as a
iOS developer. :-)

Very Rails like, I know. I tend only to use the resources and/or resource
method keywords. No custom matches and etc. Not for the API anyways. Just my
two cents.

------
jwillgoesfast
I feel like this is missing something, perhaps a working demo.

I'm experienced in php and jquery but after 2 days of fiddling and stack
overflowing, i could not get my demo api to POST...any helpful links are
appreciated.

I was especially confused with php/cURL. .ajax seemed a bit more
straightforward but jquery/javascript is so dang hard to debug. for cURL do
you have to have any (non-default) settings installed on your servers?

------
grannyg00se
>So, $.ajax in JavaScript (jQuery) and cURL in PHP. That’s it.

This is a bit confusing. "That's it" makes it sound as though this is the
complete scope of what people mean when they say API. Somewhere it should be
made clear that we are talking about one API of a particular type.

After reading the post someone could come away with the idea that if you don't
have .ajax and jQuery or cURL and PHP then you aren't using an API.

~~~
benhowdle89
I hoped this line "From personal experience, I’ve used APIs heavily with only
two languages; JavaScript and PHP." would convey that I'm only going to be
talking about these two...

~~~
grannyg00se
But ajax and cURL aren't the entirety of dealing with APIs in Javascript and
PHP either.

------
borplk
It's "a beginner's guide" that starts with an explanation of what an API is
and then jumps straight into PHP code with cURL!

When someone just learnt what an API is and doesn't have a clear idea of what
it is or how it works an example code doesn't help at all.

When I'm asked to explain what APIs are these are the things I mention,

\- an API is a fancy name for 'a way to talk to an external service'

\- when you need to do something with an external service like Twitter you
have to use their API to communicate with them

\- an API is like a 'contract for communication' which specifies how to talk
to the external party

\- Most web APIs use the HTTP protocol as a way of communication to send
messages back and forth and they also have a method of representing data, for
example JSON or XML, that's just the same thing but a different way, using
JSON or XML is like saying the same thing in English or Spanish, using the
HTTP protocol or something else is like writing down a sentence vs shouting it
out.

\- When you use Twitter's API to unfollow someone, you don't know how exactly
the unfollow happens, you don't have to know, all you know and have agreed
with Twitter is that you ask Twitter to unfollow someone and they will do it,
so in a way, using the API you are just sending them a 'signal' to do
something. They can go ahead and change the inner workings of that API and as
long as the part that is exposed to you remains the same you don't care
because as far as you are concerned it does the same thing even though it may
be doing it in a very different way

Here's a trivial example of a real-world API,

Imagine you run a restaurant and you need to buy fresh supplies to cook your
delicious dishes every day.

You hire someone and teach them to buy the supplies as you order. You trust
them to buy good quality stuff and deliver them to you.

You agree to give them order instructions via SMS. And you agree on the
following format:

    
    
       BUY
       15 Salmon Fish
       20 Avocados
       DELIVER BEFORE 30 January 2013 14:00
       END
    

Now the person you have hired can use your 'Order API' to work with you. You
send them a message in a format that you have agreed upon and using a medium
that you have agreed (SMS).

Hope that helps some beginner who is struggling with all the fancy terms being
thrown around without explaining the principals and the simple details that
everyone takes for granted once they have passed the initial learning phase.

------
Tekker
I think the term SDK should be in there - it goes hand-in-hand with API in
terms of "traditional" development that's not web-based. I understand he
didn't go there because he doesn't do that himself, but jes' sayin'.

------
currysausage
+1 for Focus Mode.

~~~
benhowdle89
+1 for this.

