Many IT organizations built an SOA (Service Oriented Architecture) in the mid-2000s or early 2010s.Â Other businesses, never did.Â But as both sets of organizations begin looking at an API initiative they ask questions about the relationships between APIs and Services:
- Are APIs and Services the same thing?
- Should I build APIs based on existing Services (if I have them)?
- What should I do if I do not have existing Services or an SOA? Do I need to build this first?
Iâ€™ve discussed positioning of APIs and Services many times (here, here, here, and here), so letâ€™s consider the first question covered.Â In short, they have similarities but also have differences.Â They are not the same thing.
This leaves the last two questions as topic for this blog.
Of course, many APIs you build use your existing services.Â So, having Services is a big step forward in making APIs simpler to build.Â But that is not really the meaning behind this question.Â The question being asked is, should you build your APIs by looking at the existing Service interfaces and building APIs based on these?Â I have argued in the answers to the API/Service positioning that this is not a best practice.Â APIs should be based on the needs of the consumer and not the provider (i.e. Service).Â Sometimes a consumer need may match one to one with a service, but other times this is not the case.
Let me use a Retail example to illustrate this.Â Letâ€™s say a retailer is providing a mobile shopping App with a function to â€ścheck order statusâ€ť.Â The retailer IT infrastructure includes Services for CRM, Ordering, Inventory, Logistics, and many more.Â If APIs were built based on these services, there would be 4 (or more) APIs potentially involved in the â€ścheck order statusâ€ť implementation.Â The Mobile App would need to call the CRM API, get a reply, then call the ordering API, get a reply, etc. causing many network calls and parsing of replies.Â Plus, these APIs would be built generically based on the service, not consumer oriented and the API interface might change incompatibly if the service or back end were updated.Â However, if the API were built based on the needs of the consumer, then the API could be defined very simply.Â Thinking about what is required to check order status from a consumerâ€™s perspective, all I should need to provide is the order number and identity of the user.Â I receive back the order status.Â One API call can then query all the necessary systems and come back with the response.Â A single simple API call versus many and a very backward compatible API even if the back-end services are changed.
This is just one example.Â But building top down APIs based on consumer is the best practice.Â One of my suggestions is â€śthe less you consider the back-end services when you define your API interface, the simpler and more backward compatible your API will be.â€ť
But, there are always exceptions to the rule.Â There are times when building on Service interfaces makes sense:
- Early in the API initiative basic building blocks and utility APIs are needed. We are experimenting and need a portfolio of APIs to start with.Â You should recognize that these APIs are likely to change perhaps incompatibly and that later more consumer targeted APIs may be built either using these or instead of these APIs.
- Internal consumption of Services that would benefit from security, rate limiting, analytics or other values provided by APIs may be implemented using an API interface that is provider focused rather than consumer focused. This can also be used for charge back accounting.
When discussing API initiatives with IT organizations that have not previously built Services, there is a concern that they are trying to start by building the second floor of a house without having already built the ground floor.Â The real question here is, â€śDo I have to build a SOA and Services before I build APIs?â€ť
As discussed in the prior section, definition of the API interface is better done without consideration of the back-end Services (or lack of Services).Â So, for interface definition the work should be identical whether or not you have Services. Â However, once the interface is defined the API developer needs to construct the API calling back-end functions to deliver the promised reply.Â This is where the work is different.
- Create a service â€“ without the necessity to create a full SOA, you might consider creating a service (or system API) as a faĂ§ade to the back-end capability.
- Use a Microservice â€“ adding a microservice to call the back-end can provide additional flexibility to perhaps call multiple back-ends and/or perform additional business logic or data transformations before returning the results.
- Use additional integration techniques â€“ Many applications can be accessed via MQ. Using IBM API Connect and DataPower you can configure your API to call a domain on DataPower that can convert the API call to an MQ message.
Few companies are starting now with a path to build the large SOA and ESB infrastructure as defined over a decade ago.Â Newer approaches are building an agile integration tier using smaller integration microservices in more modular integration style than a single ESB.Â The IBM App Connect Enterprise product can support the traditional ESB or this more modern approach.
One approach I would NOT recommend is to build out a full SOA or suite or Services before starting your APIs.Â It would simply take too long.Â A better approach is to build from the outside in based on
defined project goals.Â Start with the definition of the APIs you need from the consumer (outside) perspective and then work inward to the back-end systems.Â You can gradually build up the internal integration tier as needed using the agile integration methodology, rather than a big multi-year project to build a full SOA.Â Of course, architecture and governance are required to ensure things are continually moving in the right direction.
Whether you have existing Services to build upon or not, as a general best practice an â€śAPI Firstâ€ť mentality is the best way to go.Â This provides the simplest API possible that is easy for the consumer to use and provides more rapid return on investment.
To understand more about IBMâ€™s thoughts on the API Economy visit the IBM API Economy website.Â IBM API Connect is IBMâ€™s complete foundation to Create, Run, Manage, and Secure APIs.Â You can find more information about IBM API Connect at the API Connect website.Â And you can also experience a trial version of API Connect.
If you have questions, please let me know.Â Connect with me through comments here or via twitter @Arglick to continue the discussion.