Imagine ordering a “ready-to-assemble” table online, only to find that the delivery package did not include the assembly instructions. You know what the end product looks like, but have little to no clue how to start assembling the individual pieces to get there. A poorly designed API tends to create a similar experience for a consumer developer. Well designed APIs make it easy for consumer developers to find, explore, access, and use them. In some cases, good quality APIs even spark new ideas and open up new use cases for consumer developers.

There are methods to improve API design — like following RESTful practices. But time and again we are seeing customers unknowingly program minor inconveniences into their APIs. To help you avoid these pitfalls, here are six of the most common mistakes we have seen developers make while creating the API — and guidance on how to get it right.

#1 Thinking inside-out vs outside-in

Being everything for everybody often means that nothing you do is the best it could be, and that is just as true for APIs. When customers turn to APIs, they are looking for specific solutions to make their work easier and more productive. If there is an API that better works to their needs, they will choose that one over yours. This is why it’s so important to know what your customers need to do their work better, and then building to fill those needs. In other words, start thinking Outside-in as opposed to Inside-Out. Specifically,

• Inside-out refers to designing APIs around internal systems or services you would like to expose.
• Outside-in refers to designing APIs around customer experiences you want to create. Read more about the Outside-in perspective in the API product mindset.

The first step to this is learning from your customers — be it internal consumer developers or external customers — and their use cases. Ask them about the apps they are building, their pain points, and what would help streamline or simplify their development. Write down their most significant use cases and create a sample API response that only gives them the exact data they need for each case. As you test this, look for overlap between payloads and adapt your designs to genericize them across common or similar use cases.

If you can’t connect with your customers — because you don’t have direct access, they don’t have time, or they just don’t know what they want — the best approach is to imagine what you would build with your APIs. Think big and think creatively. While you don’t want to design your APIs for vaporware, thinking about the big picture can make it easier to build non-breaking changes in the future. For example the image below showcases APIs offered by Google Maps. Even without diving into the documentation, looking at the names like “Autocomplete” or “Address Validation” clearly outlines the purposes and potential fit for a customer’s use case.

#2 Making your APIs too complex for users

Customers turn to APIs to bypass complicated programming challenges so they can get to the part they know how to do well. If they feel like using your API means learning a whole new system or language, then it isn’t fitting their needs and they will likely look for something else. It’s up to your team to make an API that is strong and smart enough to do what your customer wants, but also simple enough to hide how complicated the tasks your API solves for really are. For example if you know your customers are using your APIs to present information about recently open restaurants and highly rated pizzeria to their consumers, providing them with a simple API call as below would be of great help:

GET /restaurants?location=Austin&category=Pizzeria&open=true&sort=-priority,created_at

To see if your API design is simple enough, pretend you are building the whole system from scratch — or if you have a trusted customer who is willing to help, ask them to test it and report their results. If you can complete the workflow without having to stop to figure something out, then you’re good to go. On the other hand, if you catch rough edges caused by trying to code around system complexity issues, then keep trying to refactor. The API will be ready when you can say that nothing is confusing and that it either meets your customers’ needs or can easily be updated as needs change.

#3 Creating “chatty” APIs with too many calls

Multiple network calls slow down the process and creates higher connection overhead — which means higher operational costs. This is why it’s so important to minimize the number of API calls.

The key to this is outside-in design: simplify. Look for ways to reduce the number of API calls a customer must make in their application’s workflow. If your customers are building mobile applications, for example, they often need to minimize their network traffic to reduce battery drain, and requiring a couple calls instead of a dozen can make a big difference.

Rather than deciding between building distinct, data-driven microservices and streamlining API usage, consider offering both: fine-grained APIs for specific data types, and “experience APIs” (APIs that are designed to power user experiences. Here is a further theoretical discussion on Experience APIs) around common or customer-specific user interfaces. These experience APIs compose multiple smaller domains into a single endpoint; making it much simpler for your customers — especially those building user interfaces — to render their screens easily and quickly.

Another option here is to use something like GraphQL to allow for this type of customizability. Generally you should avoid building a unique endpoint for every possible screen, but common screens like home pages and user account information can make a world of difference to your API consumers.

#4 Not allowing for flexibility

Even if you’ve followed all of the steps above, you may find that there are edge cases that do not fit under your beautifully designed payloads. Maybe your customer needs more data in a single page of results than usual, or the payload has way more data than their app requires. You can’t create a one-size-fits-all solution, but you also don’t want a reputation for building APIs that are limiting. Here are 3 simple options to make your endpoints more flexible.

Filter out response properties: You can either use query parameters for sorting and pagination, or use GraphQL which provides these types of details natively. By giving customers the option to request only the properties they need, it guarantees that they won’t have to sort through tons of unnecessary data to get what they need. For example, if some of your customers only need the title, author, and bestseller ranking, give them the ability to retrieve only that data with a query string parameter.

GET /books?fields=title,author,ranking

• Ability to sort with pagination. Generally, you don’t want to guarantee the order of objects in an API response because minor changes in logic or peculiarities in your data source might change the sort order at some point. In some cases, however, your customers may want to sort by a particular field. Giving them that option, combined with a pagination option, will give them a highly efficient API when they only want the top few results. For example Spotify API utilizes a simple offset and limit parameter set to allow pagination. A sample endpoint as shown in the documentation would look like this

$ curl https://api.spotify.com/v1/artists/1vCWHaC5f2uS3yhpwWbIA6/albums?album_type=SINGLE&offset=20&limit=10

• Use mature compositions like GraphQL: Since customer data needs can differ, giving them on-the-fly composites lets them build to the combinations of data they need, rather than being restricted to a single data type or a pre-set combination of data fields. Using GraphQL can even bypass the need to build experience APIs, but when this isn’t an option, you can use query string parameter options like “expand” to create these more complex queries. Here is a sample response that demonstrates a collection of company resources with embedded properties included

"data": [
{
"CompanyUid": "27e9cf71-fca4",
"name": "ABCCo",
"status": "Active",
"_embedded": {
"organization": {
"CompanyUid": "27e9cf71-fca4",
"name": "ABCCo",
"type": "Company",
"taxId": "0123",
"city": "Portland",
"notes": ""
}
}
}
]

#5 Making design unreadable to humans

“K”eep “I”t “S”imply “S”tupid when you are designing your API. While APIs are meant for computer-to-computer interaction, the first client of an API is always a human, and the API contract is the first piece of documentation. Developers are more apt to study your payload design before they dig into your docs. Observation studies suggest that developers spend more than 51% of their time in editor and client as compared to ~18% on reference.

For example, if you skim through the payload below it takes some time to understand because instead of property names it includes an “id”. Even the property name “data” does not suggest anything meaningful aside from just being an artifact of the JSON design. A few extra bytes in the payload can save a lot of early confusion and accelerate adoption of your API. Notice how user-ids appearing on the left of the colon (in the position where other examples of JSON ideally have property names) creates confusion in reading the payload.

"{id-a}":
{ "data":
[
{
"AirportCode": "LAX",
"AirportName": "Los Angeles",
"From": "LAX",
"To": "Austin",
"departure": "2014-07-15T15:11:25+0000",
"arrival": "2014-07-15T16:31:25+0000"
}
… // More data
]
},

We think that JSON like this is more difficult to learn. If you want to eliminate any ambiguity in the words you choose to describe the data, keep the payload simple and if any of those labels could be interpreted in more than one way, adjust them to be more clear. Here is a sample response from Airlines endpoint of aviationstack API. Notice how the property names clearly explain the expected result while maintaining a simple JSON structure.

"data": [
{
"airline_name": "American Airlines",
"iata_code": "AA",
"iata_prefix_accounting": "1",
"icao_code": "AAL",
"callsign": "AMERICAN",
"type": "scheduled",
"status": "active",
"fleet_size": "963",
"fleet_average_age": "10.9",
"date_founded": "1934",
"hub_code": "DFW",
"country_name": "United States",
"country_iso2": "US"
},
[…]
]

#6 Know when you can break the RESTful rules

Being true to the RESTful basics — such as using the correct HTTP verbs, status codes, and stateless resource-based interfaces — can make your customers’ lives easier because they don’t need to learn an all new lexicon, but remember that the goal is just to help them get their job done. If you put RESTful design first over user experience, then it doesn’t really serve its purpose.

Your goal should be helping your customers be successful with your data, as quickly and easily as possible. Occasionally, that may mean breaking some “rules” of REST to offer simpler and more elegant interfaces. Just be consistent in your design choices across all of your APIs, and be very clear in your documentation about anything that might be peculiar or nonstandard.

Conclusion

Beyond these common pitfalls, we have also created a comprehensive guide packaging up our rich experience designing and managing APIs at incredible scale with Google Cloud’s API management product, Apigee.

Apigee — Google Cloud’s native API management platform — helps you build, manage, and secure APIs — for any use case, scale or environment. Get started with Apigee today or check out our documentation for additional information.

Video AI is a powerful way to enable content discovery and engaging video experiences.

Here, try it out right now!

Google Cloud’s easy-to-access video AI solutions can accomplish a bunch of things. Here are a few:

Precise video analysis: Video Intelligence API automatically recognizes more than 20,000 objects, places, and actions in stored and streaming video. It also distinguishes scene changes and extracts rich metadata at the video, shot, or frame level. Use in combination with AutoML Video Intelligence to create your own custom entity labels to categorize content. Imagine being able to categorise hundreds of videos of customer interactions quickly to improve service training!

Recommended content: Build a content recommendation engine with labels generated by Video Intelligence API and a user’s viewing history and preferences. This will simplify content discovery for your users and guide them to the most relevant content that they want.

Simplify media management: Find value in vast archives by making media easily searchable and discoverable. Easily search your video catalog the same way you search text documents. Extract metadata that can be used to index, organize, and search your video content, as well as control and filter content for what’s most relevant.Imagine being able to locate insight in hundreds of enterprise videos to improve productivity and customer experience!

Easily create intelligent video apps: Gain insights from video in near real time using the Video Intelligence Streaming Video APIs, and trigger events based on objects detected. Build engaging customer experiences with highlight reels, recommendations, interactive videos, and more. Marketers, imagine being able to trigger a customer workflow, in real time, based on a live customer interactions.

Automate expensive workflows: Reduce time and costs associated with transcribing videos and generating closed captions, as well as flagging and filtering inappropriate content.

Content moderation: Identify when inappropriate content is being shown in a given video. You can instantly conduct content moderation across petabytes of data and more quickly and efficiently filter your content or user-generated content.

What can your organisation do with video AI?

On April 6th, 2022, Google Cloud established a new partnership with CAST, to help accelerate the migration and application modernization programs of customers worldwide, complementing the Google capabilities already available through the Google Cloud Application Modernization Program (CAMP).

Application Rationalization (App Rat) is the first step towards a cloud adoption or migration journey, through which you go over the application inventory to determine which applications should be Retired, Retained, Refactored, Replatformed, or Reimagined.

Why is this important to you?

Have the majority of your in-house applications still not moved to the cloud? How much time does your development team spend on support (bug fix, tickets, etc.) versus feature(s) development? Have Infrastructure/Platform dependencies ever delayed product rollout? Would an auto-scalable, managed cloud, increase stakeholder buy-in?

Can Google simplify this journey?

Google Cloud Application Modernization Program (CAMP) has been designed as an end-to-end framework to help guide organizations through their modernization journey by assessing where they are today, and provide a path forward. When it comes to App Rationalization, this depends on what your role is.

Step 1 (Assess): Who is the target audience? The Platform team (or) the Application team?

This determines what kind of challenges we are trying to solve. For e.g. the centralized platform team wants to set some guardrails on how the App teams deploy their apps. Streamlining this would allow the platform team to mature themselves into the SRE territory. The application team, on the other hand, loves flexibility, and the ability to perform Continuous Delivery.

These examples are only the tip of the iceberg. Most of the enterprise customers have a majority of their applications in the legacy world. Unless we move those business critical applications to the cloud, it’s impossible to mature as an enterprise. For more information, check State of DevOps 2021 report.

Step 2 (Analyze): Google Cloud offers the tooling and the framework to analyze your legacy applications.

Platform Owner (persona), usually have very little information on which workloads are a good fit for modernization.

Google’s StratoZone® SaaS platform provides customers with a data-driven cloud decision framework. The StratoProbe® Data Collector Application delivers the ability to easily deploy and scale the discovery of a customer’s IT environment for Private, Public, or Hybrid-cloud planning. To ease and accelerate the VM migration journey, Google Cloud offers assistance and guidance in making the right decisions when deciding to go to cloud.

Google’s mFit aims at unblocking customers in their transformation by providing workload selection for successful on-boarding, at scale, to Anthos, GKE and Cloud Run , in both pre-sales (e.g. proof-of-concept/proof-of-value) and post-sales (e.g. pilot and at scale execution) scenarios.

App and/or Business Owners (persona), get involved in a 1-week workshop, using CAST Highlight, which would provide rapid portfolio assessment through automated source code analysis for Cloud Readiness, Open Source risks, Resiliency, and Agility.

Step 3 (Plan & execute): Each organization is different. Some may follow the “Migration Factory” approach, and some may follow “Modernization Factory”, and some may follow both. Irrespective of which approach you choose to follow, it is important to plan just enough, so that you can start your execution. Ensure to set the OKRs, that would help with the right measurements, before you start the execution. The actual learning from the execution helps the team(s) to learn more about the cloud migration process, and refine it based on their organization.

Using CAST Highlight in the assessment step previously, we get the recommendation for the analyzed applications. From there, for certain workloads, we can use Migrate to Containers, to automate the containerization of suitable workloads. However, there are certain applications that require manual code changes. You have a few options for that,

• Our experts can help you get started.
• Our partners can help you

Step 4 (Measure & reiterate): Measure the progress using the predefined metrics in the previous step. Celebrate the wins. Consistently share the learnings and best practices with the developer community. Pick the next challenge

Take the next step

Tell us what you’re solving for. A Google Cloud expert will help you find the best solution.

While many companies are writing brand-new Kubernetes-based applications, it’s still quite common to find companies who want to migrate existing workloads. A common source platform for these applications is Cloud Foundry. However, getting an existing Cloud Foundry application running on Kubernetes can be non-trivial, especially if you want to avoid making code changes in your applications, or taking on big process changes across teams. That is, if you’re not using Kf to do a lot of that heavy lifting for you. 

Kf is a Google Cloud service that allows you to easily move existing Cloud Foundry workloads to Kubernetes with minimal disruption to your existing processes. 

Kf features a command line interface (CLI) also named kf, that replaces the existing Cloud Foundry cf command line utility. The kf CLI implements the most commonly used cf functionality, including the ability to manage bindings, services, apps, routes and more. 

For example, to deploy an existing application you would simply issue the kf push command. 

On the server side Kf is built on several open source technologies. In some cases these technologies are also the Google Cloud implementation. For instance GKE is our managed Kubernetes offering,  and provides the platform for managing and running the applications. Routing and ingress is handled by Anthos Service Mesh, Google Cloud’s managed Istio-based service mesh. Finally, Tekton provides on-cluster build functionality for Kf. Developers don’t have to worry about any of those technologies, as Kf abstracts them away.

Kf primitives such as spaces, bindings and services are implemented as custom Kubernetes resources and controllers. The custom resources effectively serve as the Kf API and are used by the kf CLI to interact with the system. The controllers use Kf’s CRDs to orchestrate the other components in the system.

The beauty of this approach is that developers who are familiar with existing workflows can largely replicate those workflows with the kf CLI. On the other hand, platform operators who are more familiar with Kubernetes can use kubectl to interact with the CRDs and controllers. 

For instance if you wanted to list the apps running on your Kf cluster you could issue either of the following commands:

  kf apps
kubectl get apps -n space-name

Notice that CF / Kf spaces get mapped one to one to Kubernetes namespaces.

To get a list of all the custom resources you can examine the api-resources in the kf.dev API group.

  kubectl api-resources --api-group=kf.dev
NAME                      SHORTNAMES   APIGROUP   NAMESPACED   KIND
apps                                   kf.dev     true         App
builds                                 kf.dev     true         Build
clusterservicebrokers                  kf.dev     false        ClusterServiceBroker
routes                                 kf.dev     true         Route
servicebrokers                         kf.dev     true         ServiceBroker
serviceinstancebindings                kf.dev     true         ServiceInstanceBinding
serviceinstances                       kf.dev     true         ServiceInstance
spaces                                 kf.dev     false        Space

With Kf developers can continue to work with a familiar interface and platform operators can use declarative Kubernetes practices and tooling such as Anthos Config Management to manage the cluster. It’s really the best of both worlds if you’re looking to manage your existing Cloud Foundry applications on Kubernetes. 

If you’d like to learn more about Kf check out the video I just released on YouTube.  It reviews some of the concepts discussed here, and includes a short demo. If you’d like to get hands on, try the quick start. And, of course, you can always read the documentation.