How to use API documentation

Question

People generally say they use API documentation and code.

I'm relatively okay in JAVA language,meaning I can write simple programs. Recently for the project am working on, I'm asked to work on SOAPUI tool and am reading SOAPUI API for writing code in Groovy. While doing this, I got this question.

How to start using API documentation ( for any language/thing)? Lets says, I want to start using Google Map API or Yahoo developer API.

Is there any structured ways of reading and understanding API? Which Classes to use first or how to call or use various methods.

What one should do before reading particular API and how can one became familiar in creating things by reading and understanding API and start building things upon?

What skills one should have to do this? How to develop such skills.

Answer 1

I suggest you to start with tutorials and example code. API docs are a sort of reference, actually.

Answer 2

When I start to use a new tool/API I always first read the documentation to get an overview of what it is/what it does/how it works. The documentation usually points to a tutorial, which is what I do next. Then I'll try and create my own really simple test app that uses the API in a fairly trivial way.

By this time I've got to know the main classes and usually read the javadocs for them. I'll really only get onto the other less used classes or extra features when I have a need to.

Answer 3

1. Read the API fully and understand the requirements for each method calls. E.g. Some calls are GET/POST methods. Understand what parameters they require and their response they return.
2. Play with the API. Usually there's a Sandbox system where you can play with the API calls, etc.
3. Write your own code (however you like) and play with it until you understand the flow of the API.

Once you get the hang of it, Design an architecture that works best for the API. In essence, reading the documentation is essential in order to understand the API.

Hope this helps.

Answer 4

I was trying to figure them out recently also, mainly trying to trace out what the objects were that I had access to while write test scripts for the test cases. I was having trouble figuring out what types the log, context, testStep, etc. were in relation to the API. For me the error messages were a gold mine. When I tried something wrong it clearly stated what the type of the object was and pointed me in the right direction in the API.

Another thing that threw me for a loop that someone might find helpful if they didn't read carefully enough about Groovy to begin with (like me) is that Groovy exposes all the properties without needing to call the getter or setter. So stuff like myObj.myProp = 5 corresponds to the setMyProp(5) method in the API. Simple stuff but I was scratching my head for a few being new at it!