New to working with APIs, any good tutorials/books/guides?

[ApathyBear]

I don't understand how APIs work to save my life. I am a complete beginner. In fact, I am a bit confused on what API even means and what the meaning entails.

I am fairly competent with python, though I do lack some real world experience. Regardless, any tutorials/books/guides that deal with API for a complete beginner would be awesome.

Thanks.


PS: Something that can explain SDKs would be helpful as well.

 

[Steven D'Aprano]

I don't understand how APIs work to save my life. I am a complete
beginner. In fact, I am a bit confused on what API even means and what
the meaning entails.

API stands for "Application Programming Interface", and it essentially
means the set of interfaces, calling conventions, functions, methods etc.
of a language, library or even a single function.

For example, in Python, the API of the len() function is really simple:

- len() takes a single mandatory argument;

- that argument must be a sequence, mapping, or some other object
with a __len__ method;

- otherwise len() will raise TypeError;

- len() will always return an int;

- which is supposed to be the length of the sequence or mapping.


That's pretty much the API for the function len(). Simple, isn't it? Now,
obviously the API for an entire library is more complicated. It includes
rules for how many and what kind of arguments each function, class or
method expects; what values they are allowed to be; what sort of values
will be returned; what exceptions will be raised, and so forth.

Basically, when you read the manual for a language or library, that's
documenting the API. That's all there is to it.

 

[Dave Angel]

I don't understand how APIs work to save my life. I am a complete beginner. In fact, I am a bit confused on what API even means and what the meaning entails.

I am fairly competent with python, though I do lack some real world experience. Regardless, any tutorials/books/guides that deal with API for a complete beginner would be awesome.

At its most fundamental, the API is the documentation that makes
it practical to reuse code you didn't write yourself, or that
you wrote longer than 30 days ago.

"Application Programmer Interface" describes the functions, the
classes, the globals. The semantics, the algorithms, the
assumptions, the gotchas. The license, the restrictions.

If you inherit a body of code and it doesn't define an API,
chances are it's throwaway code, good only for examples.

PS: Something that can explain SDKs would be helpful as well.

SDK is "Software Development Kit" Generally it's a bunch of
related APIs plus one or more of tools like editor, compiler,
interpreter, debugger, profiler, test generator, IDE, source
control system, bug tracker, etc.

 

[ApathyBear]

Thanks, I think I have an understanding of what they are, but now am still a little confused on how one goes about using it: how am I supposed to knowhow to use an API in python? or in any other language for that matter? If an API is defining rules in C, is all hope lost for trying to use it in python?

Examples??

 

[Joel Goldstick]

Thanks, I think I have an understanding of what they are, but now am

still a little confused on how one goes about using it: how am I supposed
to know how to use an API in python? or in any other language for that
matter? If an API is defining rules in C, is all hope lost for trying to
use it in python?

Examples??

Google to find some sport that interest you. Read the docs and tutorial

 

[Roy Smith]

Thanks, I think I have an understanding of what they are, but now am still a
little confused on how one goes about using it: how am I supposed to know how
to use an API in python? or in any other language for that matter? If an API
is defining rules in C, is all hope lost for trying to use it in python?

API is a very generic term for Application Programming Interface. It's
just the protocol that you need to follow to communicate with some kind
of system of software package.

The documentation for an API should describe what operations are
available, how you send data to it, and how it sends things back to you.
Beyond that, there's not a whole lot that can be said because there are
so many different kinds of APIs with vastly different interfaces.

 

[Steven D'Aprano]

Thanks, I think I have an understanding of what they are, but now am
still a little confused on how one goes about using it: how am I
supposed to know how to use an API in python?

*scratches head*

Er, first you learn how to program in Python, then you read the API
documentation and do what it says. If the documentation says that the
function requires a single string argument, then you give the function a
single string argument.

I suspect that either your question is much more subtle and complicated
than your actual words allow, or you're making things much, much, much
more complicated than they actually are. In an earlier post, you said you
had some experience programming in Python. If your code works, then you
know how to use the APIs of the functions and libraries that you used.

Here I am using the API for the len() function:

alist = [1, 2, 3]
number_of_items = len(alist)


That's all. Easy, wasn't it? I'm using the API for the len() function.

If you were asking for help with some *specific* API ("I don't understand
the multiprocessing module!"), that I could get. Some APIs are
complicated, or badly designed, or badly written, or require advanced
understanding. But APIs *in general* can be as simple as len().

or in any other language
for that matter? If an API is defining rules in C, is all hope lost for
trying to use it in python?

If an API is defined for a C library or function, then, no, you can't use
it in Python, or Lisp, or Ruby, just as you can't use a Lisp function in
C or Forth or Pascal. Not unless one or the other language makes special
provision to allow such cross-language communication.


It might be better for you to give us concrete examples of what you don't
understand, rather than to continue talking in vague generalities.

 

[Cameron Simpson]

[...] or in any other language
for that matter? If an API is defining rules in C, is all hope lost for
trying to use it in python?

If an API is defined for a C library or function, then, no, you can't use
it in Python, or Lisp, or Ruby, just as you can't use a Lisp function in
C or Forth or Pascal. Not unless one or the other language makes special
provision to allow such cross-language communication.

What Steven says is true, at the simplest level.

However, MANY popular APIs that come with (for example) C libraries
and which are documented in terms of a C programming interface have
Python modules whose entire purpose in life is to present a Python
API which in turn accesses the C API for you.

For one example, consider the "bsddb" Python 2 module, which is
part of the standard library: if you have Python 2, you have the
bsddb module:

http://docs.python.org/2/library/bsddb.html#module-bsddb

The BSD dbm libraries are C libraries with a C API. However, the
bsddb module is a Python module which contains python calls which
operate on BSD dbm files. If you're using Python, you can use this
module, which of course has a _Python_ API, to use the BSD dbm
library.

So: if you have some library which has a C API, it is possible that
there is a Python module which interfaces to it, and that module
will have a Python API. You may need to fetch such a module from a
third place, such as PyPI.

Cheers,