Founded in 2014, Swiggy started small, delivering food to a few neighborhoods in Bengaluru, India. As the company grew, the team wanted a mapping technology that could help expand the service throughout India.

Swiggy needed a scalable mapping platform that covered a wide geographic area and offered tools to help the company to build an efficient mobile app and website for customers and delivery staff.

Customers find restaurants and order from them using the Android app, iOS app, or the website. Swiggy worked with Google Maps Partner Media Agility and used a variety of Google Maps Platform APIs to develop web and mobile apps that incorporate relevant local restaurant details.

Google Maps Platform Results

• Built a hyper-local delivery service that is growing throughout India at a rate of 25 percent per month
• Deliveries are made quickly, resulting in higher customer satisfaction and retention—users have been so satisfied that nearly 80 percent of its orders are from repeat customers
• Drivers seamlessly handle tens of thousands of orders per day

In order to guarantee fast food delivery, Swiggy returns only restaurants within four to five kilometers of the customer’s location. The Directions API is used by drivers to easily route to restaurants and customers. The customer can track the progress of the delivery and estimated arrival time using a mobile app or the website.

“Google Maps provides the most accurate and reliable data, which is crucial for us because maps and location are central to our business. We also knew Google’s intuitive interface would provide a great customer experience with little to no learning curve… Google Maps’ ability to provide customer location and the distances of nearby restaurants is the backbone of our success, because it ensures a reliable, consistent customer experience,” said Aman Jain, Senior Product Manager, Swiggy.

Traveloka is an Indonesian tech company currently focusing on the travel and lifestyle markets. Our customers, the majority of which come from Southeast Asia, visit the site mainly to book flights, hotels, transportation, lifestyle experiences (e.g. theme parks, movie tickets, beauty and spa treatments, and restaurant vouchers), and much more. We aim to serve more customers across the globe as part of our giant expansion plans.

In past blog posts, my colleagues have written about how Traveloka is using Google Cloud for data provisioning and stream analytics. Today, I’m sharing how we use Apigee API Management Platform from Google Cloud, a key part of my role as an engineering manager in charge of the after-sales and affiliation domain.

Extending the global footprint with Apigee

Expanding to markets globally means dealing with a lot of unique and challenging factors in each country. Thinking about different government regulations, currencies, payment systems, and customer service expectations is only the beginning.

Problems arose when partners who had connected with our flights API wanted to add another service, like accommodation. They felt like they were working with a different company. We turned to Google Cloud and found an answer.

There’s a lot of potential obstacles given how differently each country’s marketplace operates, which is why we use APIs and a partner integration approach to better distribute our inventory, thus helping us to scale our business quickly in a competitive space.

When we started Traveloka, we were serious about building a product that would be better than our competitors. Better in terms of inventories, services, and also pricing.

We also knew that we wanted to have the best strategies for increasing our exposure within and outside of Southeast Asia. With all the right features needed (security, high performance, monitoring, and low development and maintenance costs), Apigee helps us execute on our business plan, by making it quick and easy to work with the partners that make the Traveloka platform a success. 

API Gateway: Make Or Buy?

When we started, we built our own API gateway with our first version of API specifications. Before that, we looked into several API gateway products (including Apigee), did some research, some POCs, and had several meetings with vendors.

However, since we were just starting to dip our toes into the API business and didn’t have enough use cases to justify the purchase, we decided to build our own system with the bare minimum requirements. 

It used to take up to three months to deploy a new API for a partner. Now that we have the Apigee developer portal, it just takes a few days.

After a while, other Traveloka products that also wanted to have their API exposed rebuilt the same thing. Problems arose when partners who had connected with our flights API wanted to add another service, like accommodation. They felt like they were working with a different company. Different standards, different security practices, different formats—it wasn’t an optimal way to work.

About a year and a half after the release, we started to understand the scale, needs, and the limitations of our own platform. We were convinced that a better solution was needed to support our business growth. We then met with Apigee team again, at the Google Cloud Summit 2018 in Jakarta.

Aside from standardizing our APIs, Apigee supports benchmarking, a fantastic developer portal, a sandbox environment, and great monitoring and analytics. Apigee gives us remarkable speed and agility. It enables us to scale quickly, which is vital to executing our business plan to offer more services in more regions. 

I also like the rate-limiting feature that lets us limit the throughput rate from one API to another. The fact that we can do this not only per URL, but also per partner, gives us a lot of flexibility.

For example, if partner A has a throughput of 100 calls per second, but partner B needs 500, we can easily meet those differing needs and manage our traffic efficiently. When we evaluated API gateways, Apigee was the only one that enabled us to limit to that level of granularity. 

Our APIs are meant for B2B, not for the public. Because of the requirements, we need a high level of security. Apigee helps us in managing the security with its SSL handshake features as well as the authentication and authorization methods. 

Aggressive Growth with Apigee

Before we had Apigee, sharing APIs with partners was a laborious process. We exposed approximately 20 APIs through a shared document that listed our APIs with the types of the requests and responses they need to handle. Partners could see what was available and how they could integrate into our staging. More work was required before they could come in and try APIs in our sandbox.

It used to take up to three months to deploy a new API for a partner. Now that we have the Apigee developer portal, it just takes a few days.

The developer portal enables our partners to view all of our APIs and try them out in the sandbox. The simplicity in creating and managing proxies is also a huge time saver. Right now, we have two B2B partners onboarded to the developer platform, and a few more still working manually through our old, in-house platform.

We expect to transition them over and add 20 new partners to the Apigee platform this year. Because it now takes us as little as two weeks to onboard a new partner from first establishment to go live, we’re ramping up quickly. We estimate that we saved at least a year of development time by deploying the Apigee platform as opposed to building one in-house.

Rapid Learning, Rapid Onboarding

Our developers are very happy with Apigee and feel the portal makes Traveloka look more professional. Equally important, the Apigee learning curve for developers and partners has been short. In just one week our partners know how to use all our APIs. If you compare that to the previous process of referring to a Google Doc and building their own servers to connect to our staging, it’s incredibly easy.

We look forward to exploring other ways that the Apigee platform can help Traveloka; we see strong potential to use even more features to help Traveloka grow and stay competitive.

New locations in Eventarc

Back in August, we announced more Eventarc locations (17 new regions, as well as 6 new dual-region and multi-region locations to be precise). This takes the total number of locations in Eventarc to more than 30. You can see the full list in the Eventarc locations page or by running gcloud eventarc locations list . 

What does location mean in Eventarc?

An Eventarc location usually refers to the single region that the Eventarc trigger gets created in. However, depending on the trigger type, the location can be more than a single region:

• Pub/Sub triggers only support single-region locations.
• Cloud Storage triggers support single-region, dual-region, and multi-region locations.
• Cloud Audit Logs triggers support single-region locations and the special global region.

Before looking into trigger location in more detail, let’s look at other locations relevant in Eventarc.

What other locations are relevant in Eventarc?

Triggers connect event sources to event targets:

Each event source, event target, and trigger has its own location. Sometimes, these locations have to match and sometimes they can be different.  

Here’s an example of a trigger connecting Cloud Storage events from a bucket in the europe-west1 region to a Cloud Run service in the us-central1 region with a trigger located in the europe-west1 region:

  gcloud eventarc triggers create trigger-storage \
  --destination-run-service=hello \
  --destination-run-region=us-central1 \
  --location=europe-west1 \
  --event-filters="type=google.cloud.storage.object.v1.finalized" \
  --event-filters="bucket=my-bucket-in-europe-west1-region" \
  --service-account=$PROJECT_NUMBER-compute@developer.gserviceaccount.com

In many cases, you don’t have control over the location of the event source. In the example above, the Cloud Storage bucket is in the europe-west1 region. That’s the location that you need to work with and it has implications for the trigger location (which I’ll get to later). 

The location of the event target is the region of the service where you want the events to go. You get to choose this from one of the supported regions when you deploy your Cloud Run service. You typically want this to be in the same region as your event source for latency and data locality reasons (but this is not strictly a requirement). In the example above, the event source (bucket) is in europe-west1 but the event target (Cloud Run service) is in  us-central1 as specified by the --destination-run-region flag. 

The location of the trigger is dictated by the event source location, but the trigger type also comes into play. It is specified by the –location flag. Let’s take a look at the trigger location for each trigger type in more detail.

Location in Pub/Sub triggers

In a Pub/Sub trigger, you connect a Pub/Sub topic to an event target. Pub/Sub topics are global and not tied to a single region. However, when you create a Pub/Sub trigger, you need to specify a region for it (because Eventarc triggers need to live in a region) with the --location flag as follows:

  gcloud eventarc triggers create trigger-pubsub \
  --destination-run-service=hello \
  --destination-run-region=us-central1 \
  --location=us-central1 \
  --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
  --transport-topic=projects/your-projectid/topics/your-topic

By specifying a location, Eventarc automatically configures the geofencing feature in Pub/Sub such that events only persist in the specified location. As I noted above, you typically want to (but are not required to) choose the same region for the trigger and the Cloud Run service for lower latency and data locality. You can also use regional Pub/Sub service endpoints to publish to the topic to ensure that all of the data stays in a single region. 

Location in Cloud Storage triggers

In a Cloud Storage trigger, you connect a Cloud Storage bucket to an event target. A Cloud Storage bucket can be in a single-region (e.g. europe-west1), dual-region (e.g. eur4), or multi-region (e.g. eu) location. The location of the bucket dictates the location of the trigger and they have to match. The earlier trigger example was for a bucket in the  europe-west1 single-region location. Here’s another trigger connecting Cloud Storage events from a bucket in the eu multi-region location. Notice how the location flag matches the bucket region:

  gcloud eventarc triggers create trigger-storage \
  --destination-run-service=hello \
  --destination-run-region=us-central1 \
  --location=eu \
  --event-filters="type=google.cloud.storage.object.v1.finalized" \
  --event-filters="bucket=my-bucket-in-eu-multi-region" \
  --service-account=$PROJECT_NUMBER-compute@developer.gserviceaccount.com

If the bucket region and the trigger region do not match, you’ll see an error:

  ERROR: (gcloud.eventarc.triggers.create) INVALID_ARGUMENT: The request was invalid: Bucket "my-bucket-in-eu-multi-region" location "eu" does not match trigger location "europe-west1". Try again by creating the trigger in "eu".

Location in Cloud Audit Logs triggers

In a Cloud Audit Logs trigger, you connect any event source that emits Audit Logs to an event target. The location of the event source will dictate the trigger location. This is typically a single region but there is a special global region that’s necessary in some cases. 

For example, if you want to read Cloud Storage events from a bucket in the europe-west1 region with an Audit Logs trigger, you will create the trigger with the same location. Note that this will match all buckets in the europe-west1 region as there’s no filter by bucket in Audit Logs:

  gcloud eventarc triggers create trigger-auditlog \
  --destination-run-service=hello \
  --destination-run-region=us-central1 \
  --location=europe-west1 \
  --event-filters="type=google.cloud.audit.log.v1.written" \
  --event-filters="serviceName=storage.googleapis.com" \
  --event-filters="methodName=storage.objects.create" \
  --service-account=$PROJECT_NUMBER-compute@developer.gserviceaccount.com

On the other hand, if you want to match a dual-region or a multi-region bucket such as eu, you will create the trigger with the global location as Audit Logs triggers only support a single or global region. Note that this will match all buckets in all regions globally:

  gcloud eventarc triggers create trigger-storage \
  --destination-run-service=hello \
  --destination-run-region=us-central1 \
  --location=global \
  --event-filters="type=google.cloud.storage.object.v1.finalized" \
  --event-filters="bucket=my-bucket-in-europe-west1-region" \
  --service-account=$PROJECT_NUMBER-compute@developer.gserviceaccount.com

As you can see from this example, if you want to read Cloud Storage events, the native Cloud Storage trigger is a much better option, but this example illustrates a typical case in which a global Audit Log trigger is necessary. 

That wraps up this closer look at locations in Eventarc. Feel free to reach out to me on Twitter @meteatamel for any questions or feedback.

The benefits of APIs are becoming more clear in an ever-evolving tech landscape, yet ITDMs still struggle to convince executives and investors to buy into an API-first strategy. Here’s a look at the importance of APIs in a changing world, and how ITDMs can make the business case in order to secure the best API strategy for their organization.

According to Google Cloud’s new “State of the API Economy 2021” report, a majority of IT decision-makers view application programming interfaces, or APIs, as essential ingredients in improved customers experiences, expanded partner engagement, accelerated innovation, and other demands of today’s business environment. This is encouraging: APIs are how software talks to other software, and since much of digital transformation involves combining disparate data and functionality into rich user experiences and process automations, APIs are an essential ingredient in modern business strategies. 

What’s less encouraging: the research surveys primarily IT professionals, not business leaders. It’s clear that IT people see the benefits of APIs in the ever-changing tech landscape, but we still hear regular concerns from these same people that they have trouble convincing executives and investors to buy into an API-first strategy. In this article, we’ll look into why they are having these difficulties and some proven ways to successfully position an API strategy not just as a technological solution, but also as a business requirement.

The importance of APIs in a changing world

The rise of APIs has been heavily influenced by the introduction of disruptive new business models and evolving customer preferences that traditional technologies are not positioned to quickly and efficiently address. 

For example, traditionally, if your business sold tickets to events, it would build physical ticket booths and maybe a website or first-party mobile app. Today, tickets in many cases aren’t so much a physical thing presented to an usher as a digital code that an usher scans. Likewise, tickets are less-often purchased in person as opposed to online, and reliance on a first-party website can be unnecessarily restrictive. It places the burden on the business to attract customers, whereas surfacing organically in social media, search engine results, and other digital experiences lets the business meet customers where they’re already assembled. 

Moreover, as COVID-19 continues to disrupt events throughout the world, many ticket sellers—and most organizations, for that matter—have pivoted to digital-first business interactions as a matter of necessity. All of these changes in the business model, and all of the interacting systems and functionality that underpin them, rely on communication among APIs. 

Similarly, today’s banks cannot grow by simply building more branches or hiring more tellers. Instead, they need to make financial information and functionality available when and where customers require it, whether that means via an ATM, a first-party app, or within some other digital experience. Many banks also need to do more than just present this functionality, as customers are increasingly interested in the analytics and insights their spending patterns can yield. Again, all of these interactions—from customers making a purchase within an app to banks applying machine learning in order to offer customers financial insights—are enabled by APIs.     

Related: The “State of API Economy 2021” report describes how digital transformation initiatives evolved throughout 2020, as well as where they’re headed in the years to come. Download for free.

When guidance meets resistance

These examples do not illustrate technology that updates the status quo, but rather technology that unlocks business opportunities that transcend the status quo—and that help businesses to thrive even as the status quo fades into irrelevance and obsolescence. APIs are thus not just an IT topic but also important business enablers that should be understood by everyone involved with the enterprise’s investments, from internal stakeholders approving business strategies to external shareholders trying to assess an organization’s trajectory. 

The challenge for investor relations is to convey these financial and operational benefits in a way that clearly communicates the need for a new business model rather than refinements to the existing models. It’s essential that IT professionals understand APIs, but it’s also essential for business leaders to understand them too.

This is even trickier given that arguments for API investments are often based on future potential, while arguments for more conservative alternatives are based on past success. 

At a high level, the API value proposition is clear: In the past, valuable functionality and data have been encased in systems and applications, making them difficult to scale or leverage for new, evolving use cases. In contrast, APIs make functionality and data infinitely reusable, infinitely scalable, and modular such that APIs can easily be combined for new uses. All of this accrues to richer user experiences and more flexibility than ever for companies to monetize their digital assets, share them with partners, or combine them with assets from third parties. 

It’s essential that IT professionals understand APIs, but it’s also essential for business leaders to understand them too.

But investors typically want as much information as possible because their decisions can affect not just productivity and output, but company stock prices and potential future growth. High-level arguments may not be persuasive. The deeper assurances investors crave would normally come from guidance.

Guidance in this context refers to insights based on growth forecasts and customer adoption, but this can be difficult early in market entry. Robust forecasting processes need to be developed to demonstrate the efficacy and value of the API economy, which can be hard to predict: whereas APIs are well understood in some sectors, and especially among digital natives, they are in the early stages of the growth rate in other verticals, making it challenging to forecast developer adoption of a given API. And since there is a shortage of information, trying to use traditional guidance comes with a risk of being wrong and thus of little value to investors.

Related: Set your 2021 API resolutions with these top 2020 posts.

How to deliver a more useful value proposition

While guidance may be premature during the early stages of market entry, investor relations teams still need to convey the full value of an enterprise to investors. To do this, they need a value proposition that emphasizes the intrinsic value of the investment while reinforcing the benefits that can best drive business and stock growth. Considering how large an investment of time, effort, and money transitioning to an API economy can be, it is vital to convey that the benefits are substantial.

A solid value proposition should demonstrate maximum returns, and while this shouldn’t include far-fetched or unobtainable claims, it can include reasonable aspirational visions alongside statistical insights. To craft these aspirational narratives, investor relations teams should look to their organization’s existing business needs and challenges, and then demonstrate how APIs can benefit the organization in these areas. Here are some options that speak to a number of common business requirements:

• Sales channel: API investments are reusable, improve speed to market, enable automated processes and partner onboarding, and can uncover unanticipated opportunities.
• Cost: Businesses can reduce operational costs by using and reusing APIs for innovation and business development, and by using the services native to your partner’s digital surface, you can further reduce innovation costs and risks.
• Earnings: API-enabled digital ecosystems unlock a variety of partner services that leverage the business’s shared data to drive new customer acquisition, new market positions, new transaction volumes, and direct API monetization.
• Risk mitigation: By investing in a credible API, businesses can mitigate downside risks that traditional enterprises can face from market disruptors, industry-wide shifts to digital tools, and inabilities to ingest and analyze growing data sources.
• Intellectual property: Unlike project-driven innovation and customized, point-to-point integration that traps enterprise knowledge in small teams and divisional silos, APIs are reusable and modular, breaking down silos and encouraging intra-organizational collaboration.
• Speed to market: The efficient, repeatable API interface informs improvements to the fulfillment process with consistent access to data from across the organization, which drives solutions that more quickly and efficiently meet customer needs.
• Ethics: APIs offer the flexibility and economical advantages that give organizations the capacity to focus on their brand’s ethical “reason for being” beyond profitability by serving economically marginal and underserved market segments.
• Customer credibility: Organizations can deliver the extended, connected digital experiences that customers expect with the tools and flexibility included with API products.
• Employee retention: Businesses can avoid losing key employees by updating their legacy technologies with APIs, giving employees the opportunity to enhance their skills with modern technologies.
• Corporate strategy: Enterprises that use APIs’ reusable, modular structure and tools are more capable of adapting to rapid structural shifts in customer demand patterns and sectoral changes in the economy.

Whichever of these business challenges a team speaks to, it is imperative that they demonstrate the benefits of APIs, and that once they’ve determined the angle they intend to use, they keep their message consistent. While we’ve seen a number of viable ways to position APIs as a winning strategy, switching among them could make the presentation—and APIs in general—seem insubstantial and unreliable. 

This is why it’s key to decide on the most relevant business concerns, and once you’ve tailored your presentation, to make sure that you have message alignment, including buy-in and support from C-level executives. With a strong pitch built around solving existing business concerns and solidarity from relevant stakeholders, you can go into your investor meeting with the confidence to secure the best API strategy for your organization.

Strengthen your pitch with additional insights. Here are five key trends in 2021 for API-first digital transformation.

About the Author: Paul Rohan is a researcher on Open Banking and a Google Cloud solutions consultant. Paul works with banking C-Suites that are examining the impact of the Platform Economy and Digital Ecosystems on financial services industry growth, market structures and governance. Paul is the author of “PSD2 in Plain English” and “Open Banking Strategy Formation”.

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.