Rule of thumbs for API designing

I have just read a very interesting article "API Design Matters" by Michi Henning. He discusses the problem with bad designed and gives some rules of thumb. We all have some time used an API that does not feel right and makes the coding hard. It is very interesting to read Michis analyze of this and why. My feeling is that he had put the hammer right on the nail. Here is a summary of the rules he discuss. I assume you will feel like me when you read them; yeah thats obvious. But thats the nice thing and the important is to get the list.

An API :
  • must provide sufficient functionality for the caller to achieve its task.
  • should be minimal without imposing undue inconvenience on the caller.
  • should be policy free if it is general purpose.
  • should be policy rich if it is special purpose.
  • should be designed from the perspective of the caller.
  • don't let the caller configure "everything".
  • should be documented before it is implemented.

If you want to read the discussion behind the rules, go to the article.

Comments

Anonymous said…
https://youtu.be/heh4OeB9A-c is also a really good old classic for great API design. At Tink we are also advocating for https://cloud.google.com/apis/design/.
March 16, 2019 at 9:51 AM
Post a Comment

Popular posts from this blog

Circles in PostGIS

Image
OGC and PostGIS has no data type to represent a circle. Instead one use ST_Buffer(geom, distance) to get a geometry that covers the area within the distance to geom . So if geom is a point you get a circle. But it does not return an exact circle. The circle is approximated represented by a polygon using eight points. One can increase the precission by adding a third argument to ST_buffer that is the number of points in the polygon returned. The unit for distance depends on what SRID is used. But what if you have a geometry that you know is a circle created with the method above? There is no exact method as far as I know, but her comes a good approximation. First we want the origo of the circle. ST_Centroid(geom) comes to handy. It returns the centeroid point of the geometry, in this case the origo of the circle. To get the radius we pick out the first point in the polygon returned by ST_Buffer with PointN(ExteriorRing(geom),1) . We need to call ExteriorRing to get the polygon of
Read more

Create your own CA with TinyCA2 (part 1)

Image
A Certificate Authorities (CA) issues certificates to people and organization that gives us the possibility to know that we surf to the right web site and not a phising site. This concept can be nice to use on your private sites too, but you may not want to spend a lot of money to get a certificate for your site. Most common when one installs a web-mail server at home is using a self signed certificate. When one surf to the web-mail server from a friends computer one can not be sure that nobody listens to the traffic if one not verifies the signature of the self signed certificate. Maybe an easier and definitely a more scalable solution to this is to create ones own CA structure. When we are ready with this how to you will have installed a certificate on your web server, installed the root certificate into your Firefox, and you will have the root certificate stored on a USB-memory stick. First time you want to read your mail from a friends computer you install the root certificate f
Read more

Create your own CA with TinyCA2 (part 2)

Image
In part one of this series we created a root CA, a sub-CA and a certificate for our web site All certificates are stored in TinyCA2 s configuration. In this part we will: export the root CA:s certificate import the root CA:s certificate into Firefox export the certificate for the web site configure our web server to use the web site certificate To be able to import the root CA certificate to Firefox we must export it from TinyCA2. In the main window of TinyCA2, open the CA-menu and select Open CA. Select your root CA. Select Export CA Certificate in the toolbar, which is the second icon from the right. You may change the file name. Press Save when ready. Start Firefox, select the Edit-menu and Preferences. Click the Advanced icon and then the Encryption tab. Select View certificates and then the Authorities tab. You can see all the CA:s you trust. Click Import and select the file with your exported root certificate. You can in the Downloading Certificate window control what purpo
Read more