Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How do you define a good or bad API? [closed]

Tags:

api-design

api

Background:

I am taking a class at my university called "Software Constraints". In the first lectures we were learning how to build good APIs.

A good example we got of a really bad API function is the socket public static void Select(IList checkRead, IList checkWrite, IList checkError, int microseconds); in C#. The function receives 3 lists of sockets, and destroys them making the user have to clone all the sockets before feeding them into the Select(). It also has a timeout (in microseconds) which is an int, that sets the maximum time the server can wait for a socket. The limits of this is +/-35 minutes (because it is an int).


Questions:

  1. How do you define an API as 'bad'?
  2. How do you define an API as 'good'?

Points to consider:

  • Function names that are hard to remember.
  • Function parameters that are hard to understand.
  • Bad documentation.
  • Everything being so interconnected that if you need to change 1 line of code you will actually need to change hundreds of lines in other places.
  • Functions that destroy their arguments.
  • Bad scalability due to "hidden" complexity.
  • It's required from the user/dev to build wrappers around the API so that it can be used.
like image 637
fmsf Avatar asked Jan 22 '09 13:01

fmsf


People also ask

How do you define good API?

In general, an effective API design will have the following characteristics: Easy to read and work with: A well designed API will be easy to work with, and its resources and associated operations can quickly be memorized by developers who work with it constantly.

What makes a good API vs a bad API?

Consistency. For sure, one important aspect of a good API (if not the most important one) is consistency across endpoints, its structure, the request & response formats and everything that goes into consuming it.

What is closed API?

A closed API, on the other hand, is one that individuals can only access through an organization's internal IT estate or a private network.


1 Answers

In API design I've always found this keynote very helpful:
How to Design a Good API and Why it Matters - by Joshua Bloch

Here's an excerpt, I'd recommend reading the whole thing / watching the video.

II. General Principles

  • API Should Do One Thing and Do it Well
  • API Should Be As Small As Possible But No Smaller
  • Implementation Should Not Impact API
  • Minimize Accessibility of Everything
  • Names Matter–API is a Little Language
  • Documentation Matters
  • Document Religiously
  • Consider Performance Consequences of API Design Decisions
  • Effects of API Design Decisions on Performance are Real and Permanent
  • API Must Coexist Peacefully with Platform

III. Class Design

  • Minimize Mutability
  • Subclass Only Where it Makes Sense
  • Design and Document for Inheritance or Else Prohibit it

IV. Method Design

  • Don't Make the Client Do Anything the Module Could Do
  • Don't Violate the Principle of Least Astonishment
  • Fail Fast - Report Errors as Soon as Possible After They Occur
  • Provide Programmatic Access to All Data Available in String Form
  • Overload With Care
  • Use Appropriate Parameter and Return Types
  • Use Consistent Parameter Ordering Across Methods
  • Avoid Long Parameter Lists
  • Avoid Return Values that Demand Exceptional Processing
like image 89
Tim Avatar answered Oct 02 '22 12:10

Tim