This is part five of the API design best practices series.
Building a solid foundation to ensure the scalability and longevity of your API is crucial, but just as crucial is ensuring that developers can understand your API, and trust it to respond with the appropriate header codes and error messages.
First off, let me apologize for the delay in this third part of the hypermedia sub-series. Christmas meant a warm trip back to Minnesota, a road trip through the Texas panhandle, and numerous snow storms in between — until finally I had the chance to cut through the mountainous desert of Southern California on my way back to beautiful San Francisco.
Now I understand some of you are probably wondering what any of that has to do with this post, other than it’s about 3 weeks after promised. One of the greatest challenges of the drive was battling my way through the snow and construction, and just hoping that the interstate would stay open (they literally close the interstates if it’s bad enough). But the one thing I could be sure of was that at every turn, between my steady GPS and road signs, I knew where I was going, and I knew when my path was being detoured or I couldn’t take a certain road… I knew this, because everything was nice and uniform.
Hypermedia sounds great in theory, but theory only goes so far. Where hypermedia really shines, or completely fails, is in implementation. Unfortunately, as hypermedia is still a relatively new aspect of web based APIs, there isn’t one specified way of doing things. In fact, you’ll find that even some of the most popular APIs operate completely differently from each other.
This is part four, sub-series 1, of the API design best practices series.
One of the challenges to implementing and correctly using hypermedia in your REST API is first understanding what hypermedia is, and what it means to use hypermedia as the engine of application state (HATEOAS).
This is part three of the API design best practices series.
Once you have an understanding of what your API needs to be able to do in order to meet your developer’s requirements, it’s important to ensure that it remains as flexible and extendable as possible. Taking advantage of best practices not only means that your API will be familiar to developers, but also ensure that it remains fluid enough to extend and build on top of it in the future. Here are this week’s best practices to help keep your API agile:
This is part two of the API design best practices series.
I cannot stress the importance of spec driven development enough. One of the quickest ways to kill your API is to define the API in your code, instead of coding to its definition. By utilizing an API modeling spec such as RAML you can quickly build out your API in a consistent manner using code and pattern reuse.