6 Replies - 1743 Views - Last Post: 21 February 2014 - 07:54 PM Rate Topic: -----

#1 apathybear7  Icon User is offline

  • New D.I.C Head

Reputation: 0
  • View blog
  • Posts: 35
  • Joined: 19-June 13

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

Post icon  Posted 21 February 2014 - 01:17 AM

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.

Is This A Good Question/Topic? 0
  • +

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

#2 jon.kiparsky  Icon User is offline

  • Pancakes!
  • member icon


Reputation: 7958
  • View blog
  • Posts: 13,554
  • Joined: 19-March 11

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

Posted 21 February 2014 - 07:47 AM

The concept of "API" is actually sort of poorly specified, and I think a lot of people are confused when they try to figure out exactly what it means.

In a nutshell, the API is the set of functions a given library exposes for your use. It's the set of actions that you can take with that library. By extension, people will sometimes speak of an API, meaning the code that backs up that set of functions, and they'll sometime speak of "check the API", most likely meaning the documentation about how that API works. At least, I've heard both of those meanings in conversation.

So for working with an API, say re, in python, you're mostly just learning what sorts of objects are defined there, what methods are offered, and so forth.

The idea of the API is that it's an interface - that is, it's the border between you and some code that has been left lying around for you to use. You don't want to care about the code, you're more interested in using someone else's work to advance your interests, so you look at what the code can do for you. The API defines that, and the associated documentation spells it out (hopefully) in some detail.
Was This Post Helpful? 4
  • +
  • -

#3 apathybear7  Icon User is offline

  • New D.I.C Head

Reputation: 0
  • View blog
  • Posts: 35
  • Joined: 19-June 13

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

Posted 21 February 2014 - 01:09 PM

Probably the best explanation I have read thus far, thank you!

One question, how am I supposed to know how to use an API in python? or in any other language for that matter?

If it is the case that the API is written in C, is all hope lost if I want to use it in python?

Examples??

View Postjon.kiparsky, on 21 February 2014 - 07:47 AM, said:

So for working with an API, say re, in python, you're mostly just learning what sorts of objects are defined there, what methods are offered, and so forth.

What is re? Regular expression? I have learned about those briefly. How is re an API? Isn't it built into python?


Thanks!
Was This Post Helpful? 0
  • +
  • -

#4 jon.kiparsky  Icon User is offline

  • Pancakes!
  • member icon


Reputation: 7958
  • View blog
  • Posts: 13,554
  • Joined: 19-March 11

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

Post icon  Posted 21 February 2014 - 02:16 PM

*
POPULAR

Quote

What is re? Regular expression? I have learned about those briefly. How is re an API? Isn't it built into python?


re is a standard module included in your python distribution, which handles regex. It's an API in the sense that it's a set of objects which expose certain functionality through a known interface. It's "built in" in the sense that you get it with the standard python distro, but it's not part of the language per se. It's a bunch of code that someone wrote to help you do stuff. So it's a good example of an API.


Quote

One question, how am I supposed to know how to use an API in python? or in any other language for that matter?


If the API is written in python, it should ideally be well documented, so you can start by exploring it in the interpreter. The two useful functions for that are dir() and help(). dir() shows you the "contents" of an object - basically, its methods and fields. You're interested in the methods, mostly.
help() shows you the inline documentation provided by the author.
So taking re as an example, you might start by just poking around:

>>> import re
>>> dir (re)
['DEBUG', 'DOTALL', 'I', 'IGNORECASE', 'L', 'LOCALE', 'M', 'MULTILINE', 'S', 'Scanner', 'T', 'TEMPLATE', 'U', 'UNICODE', 'VERBOSE', 'X', '_MAXCACHE', '__all__', '__builtins__', '__doc__', '__file__', '__name__', '__package__', '__version__', '_alphanum', '_cache', '_cache_repl', '_compile', '_compile_repl', '_expand', '_pattern_type', '_pickle', '_subx', 'compile', 'copy_reg', 'error', 'escape', 'findall', 'finditer', 'match', 'purge', 'search', 'split', 'sre_compile', 'sre_parse', 'sub', 'subn', 'sys', 'template']



The stuff in CAPS is likely to be constants and stuff that you're not really interested in just now. Functions with underscores are usually intended for internal use. The stuff you want to zoom in on is the functions like "compile", "match", and so forth. So you might check out what

>>> help (re.compile)


produces.

compile(pattern, flags=0)
    Compile a regular expression pattern, returning a pattern object.



Hm. What's a pattern object? Let's try it and see.

>>> pat = re.compile("foo")
>>> type (pat)
<type '_sre.SRE_Pattern'>



Okay, so that's given us something that looks like a pattern. What can a pattern do?


>>> dir (pat)
['__class__', '__copy__', '__deepcopy__', '__delattr__', '__doc__', '__format__', '__getattribute__', '__hash__', '__init__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', 'findall', 'finditer', 'flags', 'groupindex', 'groups', 'match', 'pattern', 'scanner', 'search', 'split', 'sub', 'subn']



>>> pat.match ("foo bar baz")
<_sre.SRE_Match object at 0xa262db0>



Okay, so it gives us a match object. Let's take a look at that:

>>> dir (_)   # underscore in the interpreter just means "the return from the last instruction"
['__class__', '__copy__', '__deepcopy__', '__delattr__', '__doc__', '__format__', '__getattribute__', '__hash__', '__init__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', 'end', 'endpos', 'expand', 'group', 'groupdict', 'groups', 'lastgroup', 'lastindex', 'pos', 're', 'regs', 'span', 'start', 'string']




So you can probably see how this works from here. You can also review the documentation for the library as a whole:

>>> help (re)


but I often find it's more useful to go in and see what I can find, and then review the docs. It gives me a little context.

Standard library APIs are documented at the python documentation site - usually, the information is very similar, but maybe you prefer browsing it in a browser. Non-standard libraries are usually documented wherever their authors host them.

Quote

If it is the case that the API is written in C, is all hope lost if I want to use it in python?


Not at all. Python is good at communicating with native code. However, this is maybe a little more advanced, and not something I feel I have the space to cover here. I would say that's a new topic.
Was This Post Helpful? 5
  • +
  • -

#5 apathybear7  Icon User is offline

  • New D.I.C Head

Reputation: 0
  • View blog
  • Posts: 35
  • Joined: 19-June 13

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

Posted 21 February 2014 - 06:49 PM

Once again, excellent post. I wish I could give you reps more than once!


I think I have more of an understanding of APIs now. Thank you. But often time documentation is confusing and uses words I don't understand. For instance, I am trying to figure out how to use this API http://docs.kontakt.io/

The API sparks a variety of questions:
-What is REST? Why does it matter?
-What exactly is Data Model referring to? What are the list of commands, are those functions that are available?
-Under Files and libraries, it only mentions Java, Java JSON, and PHP client libraries, does this mean that it isnt inherently compatible with python?

-and finally, how would someone know all this? I am willing to learn, I am just curious as to how people know this without some kind of prior knowledge. Are their really no books/tutorials written on this stuff?



Quote

Quote

If it is the case that the API is written in C, is all hope lost if I want to use it in python?


Not at all. Python is good at communicating with native code. However, this is maybe a little more advanced, and not something I feel I have the space to cover here. I would say that's a new topic.


I am severely interested in how this is done. In fact, I am curious in general to see how python (or perhaps django even) deals with code that isn't python. If anyone where to know a good place where I can read up on this, that would be much appreciated.
Was This Post Helpful? 0
  • +
  • -

#6 jon.kiparsky  Icon User is offline

  • Pancakes!
  • member icon


Reputation: 7958
  • View blog
  • Posts: 13,554
  • Joined: 19-March 11

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

Posted 21 February 2014 - 07:36 PM

Quote

-What is REST? Why does it matter?


When you find a term that you don't understand, try looking it up to get the most basic, manager-level understanding of what it's about, and then keep on with what you're doing. Later on, if you still care, you can look into it more detail, but usually you don't need the detail just now, and trying to get to the bottom of that depth-first search is a hopeless task.

So look at the first paragraph of the linked article. If you really think you want to know more, bookmark it (file it under "ignorance") and come back to it later.


Quote

-Under Files and libraries, it only mentions Java, Java JSON, and PHP client libraries, does this mean that it isnt inherently compatible with python?


It means you can't just import it and go, the way you can with a native python library.

Why do you want to use this particular API? Is there something particular that you need this one for?
Another way to ask that: what is it you're trying to do? The library support within python is pretty tremendous - there is support for almost anything you can imagine. You probably don't need to jump through hoops.
Was This Post Helpful? 0
  • +
  • -

#7 apathybear7  Icon User is offline

  • New D.I.C Head

Reputation: 0
  • View blog
  • Posts: 35
  • Joined: 19-June 13

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

Posted 21 February 2014 - 07:54 PM

Quote

It means you can't just import it and go, the way you can with a native python library.

Why do you want to use this particular API? Is there something particular that you need this one for?
Another way to ask that: what is it you're trying to do? The library support within python is pretty tremendous - there is support for almost anything you can imagine. You probably don't need to jump through hoops.


I recently received -as a gift of sorts- some beacons(bluetooth LE hardware) from this company and I want to try to mess with them and configure them using the API. I don't see any other way to program these little guys without it.
Was This Post Helpful? 0
  • +
  • -

Page 1 of 1