API/Services

What does it mean?

Effective July 1, 2018, going forward, all teams will expose their system data and functionality through service interfaces.

• All service interfaces must be designed to be reusable.
• Systems must communicate with each other through these interfaces.
• This applies to all new service interfaces and major upgrades to existing service interfaces.
• If the Service interface is an Application Programming Interface (API), it must be discoverable within the single corporate API Catalog.

What is a service interface?

In this context, a service interface is either data or functionality a producer will share with a consumer.

Let's run through a simple example: Order data that will be stored in a database and services interfaces will be needed for:

• Data: share most recent orders stored in a database (producer) with a web application (consumer) and a data warehouse (consumer)
• Functionality: a web application (consumer) will need the ability to add new orders to the database (producer)

In this example, both service interfaces must follow the API/Services mandate.

Characteristics wanted for service interfaces

The objective of the API/Services mandate is to enable ExxonMobil systems and data to become more modular and adaptable. If you are not sure if your service interface is being designed to make this happen, use the below questions to help you with the characteristics of a modern, adaptable and reusable service interface.

Your service interface must have all 3 characteristics:

• Reusable: Is my service interface reusable?
  • When onboarding new consumers to your service interface, how easy it is for them to consume your data/functionality?
  • The goal is to move towards a more open architecture, unlocking our data and enabling modularity & adaptability.
• On-demand data/functionality access: Does my service allow access to on-demand data transmission or functionality?
  • Can we get the data in some way or form immediately after it is generated or is it scheduled to be updated once a day or once a month?
  • The goal is to allow access to data/functionality as soon as possible and remove waiting times for consumers.
• Database abstraction: Does my service provide an abstraction to the database layer?
  • Are consumers interfacing with service interfaces or are they hitting the database directly?
  • The goal is to hide all the database complexity from consumers and give producers flexibility to make changes the database layer without affecting consumers.

Examples of preferred Modern Service Interfaces:

• REST APIs: Allows the 1-to-Many pattern: 1 producer that shares one service interface (in this case an API) in a synchronous way with multiple consumers enabling reusability, real-time access to data/functionality and creating an abstraction layer from the database layer.
• Event Streaming / Broker: Allows the Many-to-Many pattern: Many producers can send events to a service interface (in this case different topics in event streaming platforms) in an asynchronous way with multiple consumers enabling reusability, real-time access to data/functionality and creating an abstraction layer from the database layer.

Who can I talk to for support?

Have a question? Checkout the Frequently Asked Questions section below. If that still does not answer your question, reach out to us for help!

• If you have questions on best practices or how to build APIs, you can check out https://goto/apis.
• To get consulting assistance, submit a request at https://goto/appconsult

Frequently Asked Questions

In order to reuse, do I have to leave my API open for everyone to consume?

No, the mandate does not say you should neglect the security aspects of APIs and leave them open in favor of reusability. Please follow appropriate API Security Best Practices and lock down your APIs when building them. Only grant access to applications/teams that require such access and manage those appropriately. Also, this will give you visibility on what applications/services are relying on your API as well.

Do I need an exception if I want to use an RFC for my service interface to share data with consumers

When you test using RFC as a service interface to share data/functionality with consumers (e.g. excel VBA to read SAP table) against the characteristics wanted for services interfaces, RFCs are proprietary and very specific tied to SAP only hence it does not enable the reusability we seek and will require an exception request.

Do I need an exception if I want to use ODBC/JDBC for my service interface to share data with consumers?

When you test ODBC/JDBC as a service interface to share data/functionality with consumers against the characteristics wanted for services interfaces, ODBC/JDBC doesn't provide the necessary abstraction from the database layer we seek and will require an exception request.

In cases where the producer and consumer are not the sme team, who is responsible for creating the API/service interface (e.g. I need to get identity information and my team doesn’t own/support the identity system)?

The application/service interface provider (producer) is responsible for the service interface. In this example the team who owns the data/service for identity should provide service interfaces that meet the characteristics we want for service interfaces. Note that funding, prioritization and product roadmap will have to be accounted for your request in case the service does not exist to meet your needs.

I want to use a service interface to get regular data feed updated from a 3rd party (e.g. Walmart) but the vendor doesn't provide an API and can only send and receive CSV files through SFTP. Do I need to ask for an exception?

Yes. Exceptions are needed even if that is the only possible way of creating a service interface for this specific use case because the characteristics of services interfaces we seek are not being met.

If we are using Mulesoft for building a service interface, do we need to submit an exception for a CSV file data transfer?

Yes you do. What you build in this case with Mulesoft requires an exception since the characteristics of services interfaces we seek are not being met.

Do we need to submit an exception for building interfaces in middleware platforms such as SAP PO or webMethods?

It is not the middleware platform that determines if an exception is needed, but if the integration meets the service interface characteristics we want. As long as they are met, no exception is needed.

Are there any data formats (e.g. JSON, XML, EDI, etc) restrictions?

No, there are no restrictions. As long as the Service Interface characteristics are met, no exception is needed.

If I break down my application to use several reusable service interfaces but there are orchestration/scheduling processes that cannot be designed in a reusable service interface way, do I need exception for that orchestration/scheduling portion of my application?

No, you don't need exception. The scheduling should contain simple logic to trigger the process using the producer reusable service interfaces. So the process can be retrigger/reused

We are building just a small application for my team in base (or an SWI) and we don't intent to share any services interfaces besides this one small application. Does this mandate applies to my case?

Yes. You should build your services interfaces with the three characteristics we want in mind even for small use cases and most important catalog them in case those services interfaces are APIs. Cataloging your APIs doesn't mean you are going to grant access to any consumers but it is important for discoverability of data and functionality.

But I’m an infrastructure engineer, does this mandate apply to my service interfaces as well?

Yes it does. For vendors, most infrastructure nowadays is software defined and comes with pre-defined APIs so if you are reusing service interfaces you should catalog them in the central API catalog. For custom built infrastructure tools (e.g.: a request form) you should build your service interfaces with the 3 characteristics we want for services interfaces in mind and also catalog them.

What about data visualization tools (e.g. Tableau, Power BI), do I need to consume only from APIs to build my dashboards?

Most of the visualization tools have the capability to read from APIs and ideally, if the producer has an API, that shouldn’t be an issue for the tools. Note that the majority of datasets that are exposed to visualization tools are already curated and best crafted for those interactions so you don't need to get an exception if your Tableau report are consuming from a data warehouse with an out-of-the-box tableau connector for example.

But my solution is for analytics, which deals straight with the database layers and large volumes of data. Does this mandate apply to Analytics use cases?

The short answer is Yes it also applies for analytics use cases. Even for Analytics, we should avoid point-to-point service interfaces as they introduce a complex spaghetti architecture that is very hard to manage and change. More details and further clarifications for Analytics can be found at:http://goto/AnalyticsGuidance.