Good API design helps developers to breathe longer and comfortable in an organisation.
Especially , if you are in product developement , putting right foucs at the time of API design helps you a lot in the long run.
Poor APIs call for a vicious circle of unhappy customers, developers cribbing - " this should not be used like this " - customer doesn't know how to use this , fixing and re-fixing continuously etc.,
In this article, I will try to put the best practices for an API design which i have read in books and from my experience .Lets begin with a small example.
The spirit of writing an API :
APIs are to be designed with not what implementor feels , but what the customer wants.
The moment API discussion starts, the focus shifts so much onto what data structure to be used,algorithms etc., which often undermines what the developer who calls your API expects.
Lets take an example :
makeDrink(false, true) is in the code.
It is clear that this API is for making a drink, but what does the paramters convey.
compare it with the following:
makeDrink(coffee,hot);
much more clear and no manual is needed, it is clear that it creates a hot coffee.
But from implementor even the first one is usable as well when creating the api :
makeDrink (boolean isTea , isHot) but this information is lost to caller.
The Second Version needs Implementor to do more vork , but adding enumerations viz.,
enum drinkcategory {Coffee, Tea}
enum drinktype{ hot,cold)
This makes it, void makeDrink(drinkcategory dc, drinktype dt); which is more writing an API in the view point of caller.
lets read more
2. API should be designed to one particular task and do it well.IT must be "absloutely" correct in what it is supposed to do.
3. Set clear expectations of what it will do and what it will not - can't please eveyone in this world with your single api ( sounds a bit exaggearated , but get the spirit of it)
4. API should be treated like a little language designed by you. Give proper naming and symmetry to the API with proper documentation.
5. Mimic patterns in core APIs of the language.
6. Fail-fast behaviour when some error occurs .
7. If you are new to api design, best way is to write code with your apis.use your experiences to remove what is not needed.
8. Keep Exceptions unchecked. A checked exception reflects a problem in interaction with the outside world, such as the network, filesystem, or 0S.
If the exception signals that parameters are incorrect or than an object is in the wrong state for the operation you're trying to do, then an unchecked exception (subclass of RuntimeException) is appropriate.
9. Most important of all is having the testability approach for your apis in mind. Its a fact that has to be accepted that one of the key reasons of why springs worked ahead of EJB is api unit-testability for developers.
10. APIs should be documented , before they are implemented.
Some Technical inputs in Java :
1. Make classes and members private as much as possible. The fields that are visible only should be static and final.
2. Keep Classes immutable as much as possible . Though it means an object for each value, It makes objects thread safe and reusable.
calendar is an example of a bad design.
3. subclass if and only when "is-a" relationship holds . Just for ease of implementation , public classes should not subclass other public classes.
Eg : Stack extends vector. - a bad one,.
4. Appropriate Parameter and return types -
Specific Input Parameters moves the errors from runtime to compile time
Use double ahead of float , dont use string if a better a type is possible since strings are slow and error prone.
5. Limit the parameters to a max of 3. Incase of longer parameters use helper classes to hold parameters
6. Interface when it is needed . Just imagine if String is an interface, it would be 1000 times diffuclt to get a semantically correct string.
on saying that interface has some good advantage if there are fewer methods. I still love runnable interface for having a single method.
7.Interfaces cannot have static methods and constructors.
Hope you like this article, keep posting your comments and suggestions.
Especially , if you are in product developement , putting right foucs at the time of API design helps you a lot in the long run.
Poor APIs call for a vicious circle of unhappy customers, developers cribbing - " this should not be used like this " - customer doesn't know how to use this , fixing and re-fixing continuously etc.,
In this article, I will try to put the best practices for an API design which i have read in books and from my experience .Lets begin with a small example.
The spirit of writing an API :
APIs are to be designed with not what implementor feels , but what the customer wants.
The moment API discussion starts, the focus shifts so much onto what data structure to be used,algorithms etc., which often undermines what the developer who calls your API expects.
Lets take an example :
makeDrink(false, true) is in the code.
It is clear that this API is for making a drink, but what does the paramters convey.
compare it with the following:
makeDrink(coffee,hot);
much more clear and no manual is needed, it is clear that it creates a hot coffee.
But from implementor even the first one is usable as well when creating the api :
makeDrink (boolean isTea , isHot) but this information is lost to caller.
The Second Version needs Implementor to do more vork , but adding enumerations viz.,
enum drinkcategory {Coffee, Tea}
enum drinktype{ hot,cold)
This makes it, void makeDrink(drinkcategory dc, drinktype dt); which is more writing an API in the view point of caller.
lets read more
2. API should be designed to one particular task and do it well.IT must be "absloutely" correct in what it is supposed to do.
3. Set clear expectations of what it will do and what it will not - can't please eveyone in this world with your single api ( sounds a bit exaggearated , but get the spirit of it)
4. API should be treated like a little language designed by you. Give proper naming and symmetry to the API with proper documentation.
5. Mimic patterns in core APIs of the language.
6. Fail-fast behaviour when some error occurs .
7. If you are new to api design, best way is to write code with your apis.use your experiences to remove what is not needed.
8. Keep Exceptions unchecked. A checked exception reflects a problem in interaction with the outside world, such as the network, filesystem, or 0S.
If the exception signals that parameters are incorrect or than an object is in the wrong state for the operation you're trying to do, then an unchecked exception (subclass of RuntimeException) is appropriate.
9. Most important of all is having the testability approach for your apis in mind. Its a fact that has to be accepted that one of the key reasons of why springs worked ahead of EJB is api unit-testability for developers.
10. APIs should be documented , before they are implemented.
Some Technical inputs in Java :
1. Make classes and members private as much as possible. The fields that are visible only should be static and final.
2. Keep Classes immutable as much as possible . Though it means an object for each value, It makes objects thread safe and reusable.
calendar is an example of a bad design.
3. subclass if and only when "is-a" relationship holds . Just for ease of implementation , public classes should not subclass other public classes.
Eg : Stack extends vector. - a bad one,.
4. Appropriate Parameter and return types -
Specific Input Parameters moves the errors from runtime to compile time
Use double ahead of float , dont use string if a better a type is possible since strings are slow and error prone.
5. Limit the parameters to a max of 3. Incase of longer parameters use helper classes to hold parameters
6. Interface when it is needed . Just imagine if String is an interface, it would be 1000 times diffuclt to get a semantically correct string.
on saying that interface has some good advantage if there are fewer methods. I still love runnable interface for having a single method.
7.Interfaces cannot have static methods and constructors.
Hope you like this article, keep posting your comments and suggestions.
No comments:
Post a Comment