Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How to interpret API documentation function parameters?

Is there a standard to interpret the syntax of function interfaces in API documentations and if yes, how is it defined?

Here is an example on how to change the color of an item the JavaScript scripting guide for Photoshop for the "fillColor" function:

fillPath ([fillColor] [, mode] [, opacity] [, preserveTransparency] [, feather] [, wholePath] [, antiAlias]) 

What is the meaning of the brackets and why are there commas in the brackets? How does this relate to the following example calls?

myPath.fillPath(myNewColor)  myPath.fillPath(mynewColor, {     mode: RGB,     opacity: .5 }) 
like image 410
dbonneville Avatar asked Jun 07 '12 03:06

dbonneville


People also ask

What are parameters in API?

Parameters define variable elements of a URL path, query parameters, headers, or a request body. You can create parameters for Paths and Path operations in your API definition. Editing a parameter. Parameters define variable elements of a URL path, query parameters, headers, or a request body.

What are form parameters in REST API?

Adding Parameter to REST Service. Parameters are used to pass and add additional information to a request. You can use parameters as part of the URL or in the headers or as part of the message body. Multiple parameter types exist - the most widely used parameters are path and query-string parameters.

How do you find API parameters?

API Parameters are options that can be passed with the endpoint to influence the response. In GET requests, they're found in strings at the end of the API URL path. In POST requests, they're found in the POST body.


2 Answers

So why is API documentation written in such a way as to confuse perennial newbs / hackers / DIYers like myself?

It's really not meant to be written that way. I'll agree there seems to be no ease of use across API documentations. However, there is a lot of cross over from older man style syntax conventions, to the modern API/namespace conventions.

Typically, the type of person who works with API, will have some background in development or at the least a 'power user'. These types of users are used to such syntax conventions and it makes more sense for the API document to follow than to try to create new ones.

Is there some mysterious document somewhere that tells people how to read API documentation?

There really is no standard, or RFC, supersekretsyntaxdoc laying around anywhere, however there is a ~30 year old file for UNIX man page synposis format which is widespread use.

Some examples of this (and answering your question) would be :

Underlined words are considered literals, and are typed just as they appear.

Square brackets ( [] ) around an argument indicate that the argument is optional.

Ellipses ... are used to show that the previous argument-prototype may be repeated.

An argument beginning with a minus sign - is often taken to mean some sort of flag argument even if it appears in a position where a file name could appear.

Almost all programming related documentation uses this type of syntax convention, from Python, man pages, javascript libs (Highcharts), etc.


Breaking down your example from Adobe API

fillPath ([fillColor] [, mode] [, opacity] [, preserveTransparency] [, feather] [, wholePath] [, antiAlias]) 

We see that fillPath() (a function) takes optional arguments fillColor, mode, opacity, preserveTransparency, feathe, wholePath or antiAlias. Calling fillPath(), you could pass anywhere from none, to all, of those parameters to it. The commas within the optional [] mean that if this parameter is used in addition to others, you need the comma to seperate it. (Common sense sometimes, for sure, but sometimes some languages like VB, explicitly need those commas to properly delineate which parameter is missing!). Since you did not link to the documentation (and I can't find it on Adobe's scripting page) there really is not a way to know which format the Adobe API is expecting. However, there should be an explanation at the top of most documentation explaining the conventions used within.

So, this function could probably be used many ways :

fillPath() //Nothing passed fillPath(#000000,RGB) // Black, in RGB mode fillPath(#000000,RGB,50) // Black, in RGB mode, half opacity  //Now it gets tricky, this might ALSO be acceptable: fillPath(#000000,50) // Black, no mode, half opacity  //OR fillPath(#000000,,50) // Black, no mode, half opacity 

Again, there usually are some standards across all documentations relating to API/programming. However in each doc, there could be subtle differences. As a power user, or developer, you ARE expected to be able to read and understand the documents/frameworks/libraries you're attempting to use.

like image 175
PenguinCoder Avatar answered Sep 20 '22 19:09

PenguinCoder


API docs for dynamically typed languages can be not very meaningful if not written carefully, so do not feel too bad about it, even the most seasoned developer can have a hard time trying to understand them.

About brackets and such, there is usually a code conventions section that should explain the exact usage outside literal examples; although EBNF, Regex and Railroad Diagrams are almost ubiquitous, so you should be familiar with them to understand most notations.

like image 24
fortran Avatar answered Sep 22 '22 19:09

fortran