3 Replies - 1057 Views - Last Post: 31 May 2012 - 07:19 PM

#1 negligible  Icon User is offline

  • D.I.C Regular

Reputation: 62
  • View blog
  • Posts: 302
  • Joined: 02-December 10

What do you want from an API?

Posted 31 May 2012 - 08:49 AM

Hey,

I've been tasked with creating an API from one of our companies class libraries, which is something I haven't done before. For the documentation I was thinking of following an MSDN style approach and having a section for each class with it's method, properties etc, along with a code snippets displaying their use.

Is there anything else I should include? What do you hate being missing/vague?

I've not really worked with well documented API's yet.
Technically this project is an API for a 3rd companies API we utilise, it has barely any documentation and had to be reverse engineered by inspecting packets and a great deal of trail and error originally. Probably why they don't want to develop with it themselves but weird eh.

This post has been edited by negligible: 31 May 2012 - 08:49 AM


Is This A Good Question/Topic? 0
  • +

Replies To: What do you want from an API?

#2 dorknexus  Icon User is offline

  • or something bad...real bad.
  • member icon

Reputation: 1256
  • View blog
  • Posts: 4,618
  • Joined: 02-May 04

Re: What do you want from an API?

Posted 31 May 2012 - 09:14 AM

I think what you include in the documentation is pretty important. I like to see things like examples anywhere that might be confusing. The JDK documentation is wonderful for this reason because it will include a brief usage example in places where it's not easy to understand. All of their documents are interlinked very well so I can navigate through different types with ease. They also include diagrams of class/type hierarchies which is very useful in OO languages.

Are you actually writing software to wrap around this existing library, or are you writing documentation for an existing API? I'm a little confused about what you are doing.

For the documentation aspect, here are some popular API docs that you could use for inspiration:

This post has been edited by dorknexus: 31 May 2012 - 09:20 AM

Was This Post Helpful? 1
  • +
  • -

#3 tlhIn`toq  Icon User is online

  • Please show what you have already tried when asking a question.
  • member icon

Reputation: 5632
  • View blog
  • Posts: 12,085
  • Joined: 02-June 10

Re: What do you want from an API?

Posted 31 May 2012 - 09:33 AM

Code snippets for each method are great. But be sure to include a good explanation of the underlying principals of the API.

I've used several OEM API's that seem to just assume you know what their designers were thinking when they build the device or the library.
  • They know the camera holds the images until you call to retrieve them, but they never actually tell you that up front.
  • They know the expected order of operation is
    • Make buffers
    • Get data as raw array
    • Call method to translate array to objects

  • They know they do all their match as integers * 100 rather than floating point because its faster, and the coder has to divide the results before displaying them to the GUI.
  • They know their methods used shared memory space and thus aren't thread-safe.

But they never explicitly tell you the underlying principals. You have to read through all the methods to get a feel for their design concepts.

A simple fully functioning application, with lots of in code comments/documentation. Even if its just a GUI with buttons and textboxes that report the results, or whatever is appropriate for the functionality of your library.
Was This Post Helpful? 1
  • +
  • -

#4 Sergio Tapia  Icon User is offline

  • D.I.C Lover
  • member icon

Reputation: 1253
  • View blog
  • Posts: 4,168
  • Joined: 27-January 10

Re: What do you want from an API?

Posted 31 May 2012 - 07:18 PM

Lots and lots of code examples of applications of your API.
Was This Post Helpful? 0
  • +
  • -

Page 1 of 1