It’s widely agreed that APIs are critical part of success in a digital business strategy. A key problem they present however is that the API ecosystem covers such a broad range of concepts â€“ from how APIs can enable new business outcomes through to detailed discussions on technical aspects of their implementation and new modelling approaches that support how they are defined and interact.
The IBM Social Program Management Open API team has spent time researching a range of these topics in the context of Social Program Management. We will present our findings in a series of blogs over the next few weeks.
How Business Outcomes can be enabled with Open APIs
Open APIs can be defined as public APIs that are robustly designed so that they serve more than one narrow use case. We can see the success of this approach in companies such as Stripe and Twitter and the trend is now being promoted in governments such as the UK governments API First policy. As we start to consider the value of Open APIs in Social Program Management however we need to ask ourselves a number of questions. How will building Open APIs help our customers? Who will be the target audience? Who are the stakeholders?
As engineers our understanding of APIs naturally began with the technical concerns. We were quick to dive into and compare the various underlying methodologies â€“ REST, GraphQL and Hypermedia. However as we compared these various possible approaches we were forced to take a step back and ask ourselves â€śWhat impact will Open APIs have on our customerâ€™s business outcomes?â€ť
Asking ourselves this question meant that we could properly evaluate each technology in line with the productâ€™s real world business use cases. Our business team gathered together research from our customers about where they saw APIs adding value and solving problems for them.
Fig 1 Integration Use Cases by Category
1. Presentation layer
Presentation layer uses cases relate to all requirements to create new views on data in Social Program Management. These could be new screens that the customer wishes to introduce or it could be a mobile app that a third party might want to develop that makes use of data from Social Program Management.
Sample Use Case
â€śAs an External developer I want to build a mobile app that allows Caseworkers to upload photos to Social Program Managementâ€ť
These use cases require APIs that have the following architectural characteristics:
Open APIs can support this use case by enabling the decoupling the front end implementation from Social Program Management. Front ends do not need to be tightly bound to narrowly defined Social Program Management facades for their data. Instead they can dynamically combine data from across one or more Open APIs using an emerging framework such as GraphQL.
2. System to System Integration
System to system use cases are ones where the requirement is to transfer data to and from Social Program Management and an External system. Typically the need is to transfer the record as soon as its generated so that the decision maker has access to the most up to date information in both applications
Sample Use Case
â€śAs a systems integrator I want to share data outbound and inbound from Social Program Management to other applications so that Caseworkers can make decisions with the most accurate informationâ€ť
These use cases have the following architectural characteristics:
Open APIs can support this use case by adopting a common standard so that its easier to integrate with other systems. In order to support sharing data outbound from Social Program Management an event driven framework such as Webhooks would need to be evaluated.
3. Bulk transfer
Many customers have use cases where they need to transfer data in bulk between Social Program Management and external systems. The most basic example of this is to support Reporting, but the same this category could also apply to a bulk upload of data to Social Program Management.
Sample Use case
â€śAs a Reporting analyst I require access to the data in Social Program Management to build a dashboard of reportsâ€ť
These use cases have the following characteristics
Open APIs help in this use case by exposing the data to the reporting user based on a well thought out domain model which doesnâ€™t require the analyst to understand the low level Social Program Management entity model.
This category covers use cases where the requirement is to make a call to an external system to get data as part of a user workflow in Social Program Management.
Sample Use case
â€śAs a caseworker I need to look up the X system when processing a Child Welfare intakeâ€ť
These use cases typically have the following characteristics
Open APIs in Social Program Management will not be a feature of this scenario since this solution required a synchronous outbound call from Social Program Management to an external system.
5. Exposing Services
Use cases in this category require that features of Social Program Management be exposed as a business service. This is the typical API Economy use case where a platform can expose an Open API in order to charge for its use.
Sample Use case
“As an external developer I would like to build a solution that consumes an Social Program Management Eligibility and Entitlement serviceâ€ť
Use cases in this category have the following characteristics
Open APIs are essential to enabling this solution. In addition to that an API gateway would need to be considered to support exposing and charging for
Thinking about business outcomes first has helped us to step back and understand what characteristics of our technical solution should be. This in turn allows us to take an API first approach to designing our APIs. Robust Open APIs are required to serve many uses cases and by keeping in mind these five categories we can ensure that our APIs are designed to be highly flexible and re-usable and suitable for all the different needs our customers may think of.