Most API libraries define one method for each endpoint. If there is an endpoint for getting user information, you might have a method like:
getUserInfo(userId);
That simple method is often a wrapper around another function that actually does the api call:
apiCall('/user/info', {userId: userId});
Another option I see less frequently is for the library to only contain the method that makes the API call.
The first method only has the advantages of code discoverability, but it isn't that big of an issue for dynamic languages. Some say it also removes the need for the developer to read documentation for the APIs, but why would you ever want somebody using APIs without reading the documentation?
The second method has three advantages that I see:
- The library is dramatically smaller
- Methods don't need to be updated if the API ever changes
- There is no need to maintain documentation for the library; the API documentation fulfills that purpose
But I don't see the second method used very often, so perhaps I'm missing something. When is it appropriate or inappropriate to use either method of writing API libraries?