APIs – a beginners’ guide(benhowdle.im)
benhowdle.im
APIs – a beginners’ guide
http://benhowdle.im/2013/01/24/apis/
14 comments
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...
But ajax and cURL aren't the entirety of dealing with APIs in Javascript and PHP either.
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!
Awesome, glad you liked it!
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.
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.
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.
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.
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.
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'.
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.
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.
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?
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?
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:
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.
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
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.
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.