Ready! API 1.7: Overcoming Challenges in Mobile API Delivery

At SmartBear, we talk to a lot of people to understand what kinds of challenges they face when building, testing, and deploying APIs. A consistent theme we hear is that people need a fast way to simulate real-world API interactions and emulate various conditions.

With our latest release of Ready! API 1.7, we introduced improvements in API traffic capture and recording from phones, IoT devices, and existing web apps to enhance our ability to meet these challenges. Before I get into that further, I wanted to share a related story.

I had a chance recently to sit down and chat with Paul Dumas, Product Owner and Manager of External API Platforms at MarketAmerica (shop.com). He had a number of insights on mobile API design and implementation which impact how systems are designed, tested, and ultimately used by subscribers.

Jump to What’s New in Ready! API 1.7

Paul Bruce: “So what’s the process of designing a mobile API like?”

Paul Dumas: “When you start building out your mobile API, it’s important to constantly think about the definitions of the business behind the software, the resources involved on the back-end, and the impact it has on consumers/customers.  You should also stop to consider “Why do I even have to think about mobile clients as something different?”.  And the answer is, mobile clients are more resource sensitive yet their users expect quick responding apps. Mobile clients need APIs that are performant and light weight, offering needed data in minimum calls.  As you’re designing your API and as you begin to think about the resources and methods, you need to maintain perspective about how clients will act on those resources. REST centers around transfer of the state of a resource.  However, the definition of a resource can vary from an atomic object (the detail item of an order) to a more elevated concept (an entire order with header and detail information together in one object).  You then need to think about how your clients can best marshal the resource, and the tradeoffs of the size of the payloads when you move from very granular resources to broader definitions of a resource.  Another familiar example could be people profiles.  If multiple addresses are needed (ship to, bill to, work, home), will you require those addresses as part of the “profile” resource or will the addresses be separated into a resource linked back to a profile?  It requires thinking about the full life cycle and transaction flow of the resource from how its stored in the back-end to how its perceived and most readily managed by your clients.”

Bruce: “Interesting. And how do the principals of REST design impact mobile API development?”

Dumas: “Well, REST doesn’t necessarily dictate your implementation of an API or resource. And while REST implies a preference for simplicity, it does not rule out configurability in API parameters to let a client have some flexibility in the resource transfer.  For example, earlier in our conversation we were basically saying that the following designs are both acceptable, with their effectiveness determined by client needs (i.e. version one for small order processes, version two for processes that do a lot of manipulation of many detail items).

Version One

[base URL]/orders/{orderID} | payload consist of order header and line item detail data

Version Two

[base URL]/orders/{orderID} | payload consists of order header data

[base URL]/orders/{orderID}/lineItems/{detailID} | payload consist of line item details

It is also an option to use parameters to let the client decide on some aspects of the resource representation.  For example:

[base URL]/people/{profileID}?addresses=yes | payload will be profile data with or without addresses

What is not negotiable is the ultimate representation of an atomic object, these must remain constant.  But, deciding if one object or a collection of them constitute a “resource” for an endpoint to manage, is the art of the design.”

Bruce: “And this is what you mean by a balance between usability and efficiency…”

Dumas: “Yes. For example, as you lift the concept of a “resource” to contain more data/objects, you have to make trade-offs such as larger payloads for fewer calls.”

Bruce: “So for mobile APIs, batching up work reduces latency across the wire. What else does it do?”

Dumas: “It’s a matter of where you do the work. Something has to be smart enough to parse or assemble the resource that is an aggregation of objects (i.e. order header and detail data), either the client or server.  If your client is often calling for a resource and then having to parse out only a portion of it, then maybe your design could be better.  On the other hand, if your API is configurable to control the payloads sent/received to some degree, then you have more opportunity for the API to implemented incorrectly.  It’s a give and take. Mobile is the more constrained client, so mobile asks for APIs designed for efficiency (performance and fewer calls).  And, mobile also has its unique considerations for security.”

Bruce: “Which brings up a good point: if something’s optimized for a mobile client experience, what about my web app or integrations that need access via API?”

Dumas: “Part of what you can do is build APIs that serve multiple client types; same API, but based on what experience the client needs, your API can accept and return variations of the payload (always adhering to the definition of the atomic objects in your API solution). Particularly in REST, you get a lot of latitude over endpoint parameters such that you can handle multiple types of client semantics. When you provide the client the opportunity to decide the tradeoff between full detail or the condensed format, you can maintain a core set of domain concepts that keep developers for both experiences in sync. It’s the same API and object representation is consistent, but the semantics differ based on what the front-end experience needs for optimization or usability sake.”

Bruce: “So one API to rule them all?”

Dumas: “Hate to use this over-used response, but it depends. It boils down to development over time. You prefer not to have duplicate APIs since there’s a higher chance of inconsistency between multiple designs, multiple iterations, and maintenance cycles.  However, if the reasons for your forked API are temporary, and when those reason are gone you can just deprecate the fork, then you are left with the simpler main version of your API.  Whereas if you try to accommodate these temporary reasons in you main API, then when those reasons subside, the complexity in your API suddenly goes from being valuable to being technical debt.”

Bruce: “We see some people chose that approach. What are some advantages using a separate API for mobile traffic?”

Dumas: “You may need to use separate APIs or endpoints for your mobile teams and your web teams for simplicity sake and to deliver sooner; just getting something out there quicker has its advantages. Being able to quickly iterate is important. And it’s obviously going to be more complex to implement multiplicity of representation in a single API.”

Bruce: “So where do you think mobile technology and APIs are headed, based on your own experience?”

Dumas: “The other day I was noticing how power outlets are always the same.  If a device needs something different than what the outlet provides, a converter is used.  It made me wonder if the best practice may be to design base APIs for the majority of clients, then have converter endpoints on the server side that provide different variations of services as needed for minority clients.  The “conversions” needed will take place server side where heavier resources can do them quickly, but the client gets the resource representation and service engagement it needs.  Then this brings up the next question, who is the majority client, has mobile taken that position?  We can’t know the future, but we have to anticipate the probable paths.”

Bruce: “That’s a great place to stop: you don’t know the future, you anticipate it. Great takeaway.”

Continuous Improvements in Ready! API 1.7

As you can see, real decisions are made with usability and iterative speed as top priorities. Accelerating the development and testing processes are challenges for managers and teams alike; SmartBear’s API tools help to automate some of the work, but it also takes leadership and critical thinking over design to minimize the complexity of APIs before they are implemented and tested.

Ready! API 1.7 introduces new features in SoapUI NG and LoadUI NG. Each release also contains incremental improvements to platform performance, compatibility, and overall stability. In this release, updates to platform include:

  • New filters for traffic capture in API discovery: host & method
  • Support for OpenID during OAuth authentication workflows
  • Performance: Faster startup time, large workspace loading, reading from large data files

New in SoapUI NG 1.7

SoapUI NG includes two new features based on popular demand from customer requests.

OpenID Connect is widely used in Single Page Applications to allow a visitor/user to identify themselves by logging in to a service provider such as Google, Facebook, or Twitter. Additionally, OAuth is often used in conjunction with OpenID Connect to validate user access. SoapUI NG now allows test engineers to build tests that simulate these OpenID workflows with support for extracting and reusing the access and id tokens present in successful authentication steps to these services.

Teams testing asynchronous APIs and webhooks now have the ability to simulate these interactions in SoapUI NG. During a long-running transaction it is common for an API client to start a transaction and provide a callback to the API. When finished, the API host sends one or more requests back to that client through the callback provided, allowing the client (an app or other API) to continue the primary workflow. SoapUI now provides a new test step (VirtResponse) that can be used to act as a recipient callback to this type of workflow, allowing for simulation of complete client/server exchange.

New in LoadUI NG 1.7

LoadUI now includes a wizard to accelerate the first-time process of creating API load tests. Also included is support for JBOSS/WildFly monitoring.

When constructing a load test, the workload, conditions, and server monitoring are important aspects of testing the overall performance of an API. Just as easy as it is to reuse a SoapUI functional test as the workload of a LoadUI NG load test, a new setup wizard navigates non-experts through the process of building out load volume and server monitoring aspects of an API load test.

LoadUI NG Pro also include additional support for monitoring JBOSS (a.k.a. WildFly) application servers where web APIs are hosted, providing enterprise Java teams improved visibility into the performance of their APIs under simulated load.

Adding to the ease of enabling API teams to proactively test the performance and scalability, LoadUI NG Pro continues to define leadership in the API economy as the world’s easiest and most comprehensive API load testing tool for enterprise software teams.

Interested in learning more about SmartBear’s API readiness tools? Learn more about Ready! API

Speak Your Mind

*