Design is all about understanding and remembering the purpose of what you are building. A convertible is fun to drive, but pretty useless if you need to bring some lumber back from the store – a pickup would work better. Unsurprisingly, APIs are no different.

Some APIs need to simply provide a more convenient way of accessing and updating information… they wrap up other systems. Their advantage is they make it easier to work with the system – using familiar HTTP calls rather than needing complex client libraries, they might provide caching or pool connections to make access more efficient – but the consumer doesn’t need to worry about the details.

Other APIs aim to provide business capabilities, supporting the activities a customer performs or the processes the business needs in order to operate. They aim to make the business streamlined and flexible – not being tied to specific provider systems. They may provide aggregated views, expose the results of business logic or describe the business using common business vocabulary.

Trying to combine a pickup and a convertible will only lead to something neither great for enjoyment nor great for carrying capacity.

So in reality it’s not ideal to combine the two different goals into a single API – otherwise you risk tying the business to specific back-ends. But likewise simply wrapping systems with an API but using business vocabulary forces consumers to implement business logic, and doesn’t make sense unless you want chaos to reign as the logic is duplicated.

So while the exposure API only approach may appear to be a good starting point, the reality is that it may give little or no benefit over point-to-point integrations without business capability APIs. At best each integration may be slightly easier because of common technology, and at worse it simply shifts complexity to API consumers forcing duplicating business logic.

When designing great APIs you have a massive opportunity to help your business create new revenue streams and partnership opportunities. The API consumption patterns, the business usage, and the universe with which your APIs will interact, make up your API design – in fact, understanding these is required for success. One of the best practices that emerged out of previous SOA efforts is to manage and publish standard information hierarchies as they relate to messages, sevices and schemas: these were called canonical models. Canonical models standardize enterprise information in predetermined structures that allow for developers and analysts to avoid having to define common structures over and over – just pick and choose them from a model.

In the REST world, canonical model structures and approach do not always translate 1 to 1.  Canonical structures tended to be very hierarchical, which doesn’t translate well to REST and JSON.  The processes used to align SOA services to the models was typically to define the operations first, followed by the canonical and the data, then ultimately the messages and schemas.  In the REST world the approach is to identify the resources, the relationship, then the methods.  Each of these steps should be much easier to do based on three approaches –

1) When identifying resources and sub-resources use a resource model that aligns to the enterprise catalog of information.  This resource model needs to be flat (not hierarchical like a canonical model) and easy to use.

2) The relationships between resources may change for a particular bounded context so allow for flexibility in the API layers to be able to navigate up and down the resources.  Take advantage of frameworks and technologies like HATEaos specialize in this approach.

3) Methods for REST should be simple and standard and focused on the resources eliminating complex naming conventions and point to point methods.

This list reviews benefits associated with using and pitfalls of not using resource models in your REST APIs.

1. If you want to design great APIs your resources must be rock solid.  Chances are you are dealing with constantly changing backend systems, numerous transformational initiatives, and a business that has financial opportunities to onboard new business partners and products with APIs.  As an API Designer you have the complex job of creating consistency in front of world that was never meant for API transactions.  Every time your consumers need to change their tech to match your changing API you are causing heartburn.  By understanding the resources and their relationships before creating your methods you will cut down on API rework and versioning thus creating a better experience for your partners, and ultimately, a better API.  Using a resource model in your design enables this approach.

2. Digital business need to be able to move quickly; don’t redefine the data every time you make an API, use a resource model.   Business concepts are quickly changing and they will be used in many implementations from events to APIs to NOSQL databases.  Having a resource model where you can “drag and drop” the resource, opposed to redefining it for every implementation will save time on the design and build while removing complex mappings and transformations that have a tendency to become massive technical debt.

3. Don’t bet your resource on a physical implementation.  Swagger, RAML, YAML, GraphQL, WADL, XSD, JSON, JSON:API, java, .Net, xslt, F# – amongst others, have all been part of the API ecosystem of my customers over the last 18 months.  Thanks to open-source contributors and the engineers that are using these standards to push the envelope of design and delivery of APIs you should expect new formats to proliferate as the API Economy becomes more and more vital to enterprises.  By maintaining a resource model at the logical level you can support the different physical implementation styles.   Managing resource models at the physical level is possible in one format but it will not translate well into implementation styles (XSD to JSON for example).  So if you want to be able to use the latest standards and not get mired down in format to format mappings use a resource model that is independent of those formats.

4. If you standardize your resource model your API adoption will increase.  Your enterprise may have dozens of duplicate representations of the same type of information in legacy transactional systems.  That doesn’t mean you need to have duplicate versions of resources.  One API layer that clearly represents the resource and allows for numerous contextual boundaries whether they are system-based, process-based, or business-based is a more ideal approach and you can get there with a well-defined resource model.  Without a model, the resources will take the shape of the legacy contexts causing proliferation of the API layers that will be more closely aligned to the dozens of legacy transactional systems.

5. APIs are not the only consideration in your design.  Resources used in enterprise APIs need to be understood by the underlying layers that perform transactions on or orchestrate information from microservices.  With a resource first approach the developer now has a leadership role in shaping where the transformations and orchestrations will need to take place to align to the resource.  Identifying resources from a model means the integration teams can expect the transformations to be aligned to the resource model opposed to a best-guess approach that may include out of date or misleading elements.  Without a well maintained resource model you may be dumping the problem to another layer that has to do complex and time consuming mappings in order to shore up the gaps between the APIs being released.

6. Out of date APIs are technical debt.  If you design resources on the fly without consulting a commonly used model, the chances are there will be gaps between what you build and how the enterprise understands your view of the resource.  Without up-to-date design documentation for that resource and the API, adoption will be poor and technical debt will increase.  In order to avoid this hassle, utilize a common resource model and defer the resource documentation to the resource product owner.

7. Your information is complex, make your APIs simple.  If you are working with a business that deals with complex information such as payment systems, premium processing, billing codes, or other information, your API consumers cannot understand the meaning just by looking at the element name.  It will be hard to on-board developers and business units that cannot decipher what the information in an API is and how to use it.  A mature resource model defines the structure of the resource but also the definition of what the data represents at a very fine grained level.  Don’t expect developers and business partners to understand the information in your resources as well as you do.  Provide examples and definitions at the resource model level and allow them to easily flow to the API providers and consumers.