Over the years of building APIs for businesses the one thing we’ve learned is that the process isn’t hard, but it needs to be well planned. Your platform design needs to be conceptualized from the very beginning. Plus, you need to implement a couple of best practices in the process. Below are a couple of tips which should set you off on the right track.
Don’t Leave the Heavy Lifting To The Consumer
If you know that an operation does not work or has a considerable side effect, then it is important not to force users to discover this issue by mistake or by poking around your API. You’ll want to do more than just return a Void or Null. You’ll also want to define success clearly by either returning a success code or by some other clear means.
Categorize the Types of Failures
Has a connection failed owing to a timeout or perhaps even if the remote host had to refuse a connection or probably because the address was long, also maybe the credentials were wrong. Whatever may be the case it should return an Enum, with each type of failure the API you’re constructing detects.
Build Support for Using Optional Parameters
Regardless of if you use overloads or the built-in language feature, it is essential to use and choose the right default values or behaviors like timeouts. All of this should give the user the option of providing the least amount of information needed to get the job done.
Consistent Calling Parameters
If the first argument is the file name in a function, that should be a convention you stick within all functions. If the arguments are arranged at random or arbitrarily, that forces the users to memorize maybe several functions which make the API platform hard to deal with.
Develop One API at a Time
You should start by identifying and categorizing the scope of your platform design and the associated API before even coding. Then make sure that you stick with the scope which should prevent you from going overboard.
Single Abstraction Level at Each Time
Yes! It may be required to have multiple layers of abstraction to get the interface you want to the user. Currently, networks can resolve a stack of 7 levels through each level should be separate so that each one can be re-used using a different top level or perhaps a different one at the bottom coded into the interface.
Ensure Isolation and Flexibility for the Configuration
All libraries that are linking back to the binary code of the application need to be configured properly as either a separate config file, application’s own config, etc. There should be at least two options which make configuring the platform design more manageable for the end user. However, one thing to keep in mind is to configure your application’s libraries using namespaces or any other similar method like the .Net’s Configuration Section which helps to keep it separate from all the rest.
Know the Exceptions You Throw
All developers are fully aware that exceptions tend to add a lot of overhead to the code and are not the best way of reporting the required outcome. However, if you determine what type of errors can be expected for the kind of API you’re developing then return codes can be sent instead of exceptions. For instance, an out of memory issue of the API can be shown as an exception. Plus, raise exceptions for errors in the code like unopened connections, out of bounds conditions and wrong arguments. You will also want to document all the exceptions thrown. The documentation gives the consumer a chance to factor all the exception handling into their designing process.