I love pigs. I really do. They’re intelligent, inquisitive, and funny. And they’re useful. It’s just that some people do not like their cuddly looks. Which makes me feel sorry for them. Poor pigs.
Chances are your IT systems are in kind of a similar state. They’re useful, robust, reliable. Perhaps their design is not exactly exemplary. But they do the job. There might be some history hidden under the cover. The result of some accidental design choices, perhaps. Unfortunate decisions in the past that are less then easy to undo today. Things you might design differently, with today’s knowledge in mind. You know, I’m quite sure you know. And perhaps you’re sorry too.
In such cases you just might consider to take some action and apply a little lipstick on your poor interfaces.
Now, I’m not necessarily talking about superficial looks here. I’m talking about the underlying design. The way the systems are structured and the way they interact. Your internal message model. After all, “Design is not just what it looks like. Design is how it works” (Steve Jobs).
This should become especially relevant when you consider opening up your systems to external developers. If you want to provide an open API. If you consider diving into the app economy. You do not want to embarrass yourself with ugly interface definitions, do you? Now if your data has not been modelled with ReSTful design principles in mind, you’re probably a bit hesitant to open up to the API economy. And you wouldn’t be the only one.
Fortunately, WSO2 has got you covered. Their API Management platform works all kind of wonders. Beautification of your API is just one of them.
How does it work?
Designing a beautiful API is, well, not exactly simple. The possibilities are endless. And different consumers may have quite different needs and preferences. Consider these strategies to get started.
- Set the standard
Perhaps there is some kind of standard in your industry you can adopt. Think of HL7 if you’re in healthcare, or eTOM if you’re in telecom. That should be a safe bet. Even if you have to design a standard yourself, it never hurts to draw some inspiration from such examples. - Embrace the external model
If customer intimacy is your driving force, you may opt to have your client applications drive your model. As a matter of fact, many API design efforts take the client UI design as a starting point. Especially for mobile apps, having a single API call for a single page makes sense (provided the UI design makes any sense).
You will most likely end up with a significant redundancy in your API model. But as long as it suits the needs of your customers, and as long as it is not too cumbersome to manage, who cares? - Co-design
If anything else fails, you’ll face yourself with the task to design something from scratch. Sounds fun, doesn’t it? Perhaps you’ll do yourself a favor starting with some good reading. The WSO2 REST design guidelines serves as an excellent introduction. After this, you’re probably good to draft your first proposal.
Importantly, you want to validate your draft before you proceed. You might feel relieved to learn that WSO2 API Manager has got you covered yet again. As API Management covers the full lifecycle of APIs, it covers design too, more specifically, it supports early prototyping. This offers your subscribers an early implementation of your API that they can play with, and provide you feedback. Test first, improve your design, implement later. And developer engagement as a bonus. How cool is that?
Now in any case, be pragmatic. Do not transpose your entire corporate data model into API definitions. Do not worry too much in advance. Rather design it just in time. You can always grow-as-you-go.,
Things to consider
Once you’ve got the design, you’ve got to think about mapping. The API gateway offers support for message mediation policies, for inbound as well as outbound messages. For simple scenarios, typically straightforward one-on-one translations, and with low volumes, this serves for an ideal start. For more complex, processor intensive operations, it’s highly recommended to offload them to a specialized node – typically an ESB. An ESB is designed to do some serious heavy lifting, such as integration with back-office systems. And a gateway, well, it’s supposed to be just that. Fortunately, with WSO2 Enterprise Service Bus, you’re free to migrate your existing mediations on the API gateway to the ESB when the time is right for you.
At Yenlo, we call this a grow-as-you-go strategy. Now this is really the beauty of the WSO2 digital innovation platform. Remember, your WSO2 digital innovation platform allows you to scale up to meet increased volumes (horizontally as well as vertically), to scale out by distributing components over specialized nodes, and to add features and functions to meet future needs. And everything can be managed as part of a consistent, integrated platform. For you, this means you can rely on the WSO2 platform to grow with your needs, and to grow just in time.
Definitions for API operations may include one or more placeholders for variables. These values are usually sent as part of the URL. Now when these values are sensitive, you want to protect is somehow. The first thing that may come to mind is sending it as part of the message body, rather than as part of the URI itself. Strictly speaking, this is not ReSTful, especially when you want to develop policies on these values. There is, however, an elegant alternative to consider.
Suppose you want to get access to a personal account. To transfer the account number in the URL might create a spoofing vulnerability or plain simply present a privacy issue. To circumvent using the (encrypted) message body, you could decide to include such a number in the JWT user token. This token can be digitally signed and encrypted. Now the application does not have to pass a value for the account number at all. The API gateway could add it as part of the mapping process, should the backend need the number. Effectively, the user can only access its own, registered account.
At some point in time, you might run into a situation where you want to control the access to your APIs. Not everything can be open to everybody always, right?
Out of the box, you’ve got two complementary mechanisms at your disposal. First, a subscription to the API itself may be restricted. It may be restricted by the user role you have, or the tenancy your account is defined in, or access granting may be subject to some kind of workflow. The latter is an advanced option to enforce more or less any business rule.
Your second option is more fine-grained. An API is a collection of methods or operations, and sometimes a subscription to an API should open up all available operations to anyone. That’s where scopes can be used. The mechanism is relatively straightforward. Without a defined scope, a method is accessible to anyone with a valid API subscription. Together with defining a scope, you define the required user roles. Once a scope has been defined, it can be attached to one or more operations inside an API definition. Now, an API consumer will need both a subscription and an appropriate user role to access a method.
With all this in mind, you may want to rethink your overall API design. Just thinking in resources is theoretically correct, but sometimes practice can be unruly. Perhaps you want to separate your internal resources from the publicly available resources. Perhaps your resources behave differently in different business domains. Perhaps…
There can be beauty in an API design – and it certainly can be ugly. That’s why we consider design a matter of craftsmanship. Good craftsmanship yields real beauty. At Yenlo, our mission is to not let technology stand in the way of creating beauty. That’s exactly what the WSO2 digital innovation platform allows us to do. And if we can help you to beautify your APIs? We’re there for you.
