What is API Collaboration?

Collaboration happens when two or more groups of people work together to solve a problem. Additionally, groups or people can also collaborate to create something (i.e music).

What’s important about collaboration is that the entities understand that they can better achieve their goals when working together.

Since collaboration happens in many domains, there are aspects of collaboration that are distinct to each domain. Furthermore, each domain may have a preferred way of collaborating. In this article, we are going to talk about API collaboration and that conversation starts with the collaboration space.

View Top API Collaboration Tools

Collaboration Space

One thing that is common across different domains of collaboration is that they all have an area where communication happens. This space is where ideas and suggestions are put forth. It can also be a place where actual work gets done.

To use the music example again, this is the recording studio. With software, a good example is Github.

Consumers and Producers

Up until this point, it may have seemed like only people creating the end product (producers) exist in a collaboration space. However, that is not the case. One of the key aspects of collaboration is that consumers are involved in the creation process.

Consumers are the voice from the outside making sure that the result is something that they want. Without the voice of the consumer, a product may completely miss the target.

API Collaboration

API collaboration can appear in different forms depending on the type of API. Regardless, once people decide they are going to build an API they take one of two approaches.

1. API-First: Design the API into a specification, using a format like OpenAPI, and then write code to fit the design.
2. Code-First: Write the code for the API and then use technology, or manually, create documentation or specifications.

There are advantages and disadvantages to either approach but both options acknowledge that the API needs human and machine-readable documentation. The key difference is when that documentation is created.

Some software exists to help define API specification, and we’ll talk about how that later when I introduce RapidAPI for Teams. Additionally, tooling exists to help generate API specifications for existing APIs. Swagger Tools is an example of one of the options.

API Lifecycle

The majority of API collaboration takes place during the beginning phases of an API’s lifecycle. An API’s lifecycle includes, but is not limited to:

• Planning and designing
• Developing
• Deploying
• Retiring or Deprecating

It’s important to note that this lifecycle applies to a single version of an API. Different APIs may use different API versioning techniques. However, the first version (“v1”) may go through this entire lifecycle. Then the lifecycle is reborn for the second version. Versions deploy breaking changes to the routes and typically require new documentation.

Some APIs may keep their previous but may drop support for them, or put them into a deprecation phase.

API Collaboration Considerations

Let’s review the main considerations that one needs to address when they plan their API collaboration.

1. Will the API be built as an API-First, or Code-First, API?
2. Who are the consumers and producers of the API?
3. Where will the consumers and producers interact (collaboration space)?
4. How can we maintain a healthy collaboration space as the API moves through its lifecycle?

You may notice that one consideration was omitted, “Where will we keep and update the code?”. The answer is—typically—Github. This is not the only option, but we will not be going into detail about other options for code repositories.

Once you feel that the above list has been answered to a satisfactory degree, you are are ready to begin!

API Collaboration with RapidAPI for Teams

API Management

Imagine starting a business. You have to consider the customers, financials, and employees. Additionally, you need to be able to secure financial transactions and protect your assets. It can be a lot to handle for one person!

Creating an API has many of the same components. It’s important to:

• Find users
• Communicate with users
• Secure transactions (API subscriptions)
• Monitor usage to protect your API from abuse
• Control who has access to the inner workings of the API

Thankfully, because APIs are technology-based services, tooling exists to help creators manage these components in convenient ways. Managers can control who is invited to work on the API and they can control who is allowed to use the API.

Furthermore, with a platform like RapidAPI, you can monitor all of your APIs down the individual endpoints regarding access and usage.

What is RapidAPI for Teams?

RapidAPI for Teams is a platform on RapidAPI that allows teams t0 access external and internal APIs and manage their usage across applications.

Administrators can create organizations, teams, and applications to get analytics on their API consumption. The analytics provide a way to pinpoint API errors, examine parameters, and view API latency down the individual endpoints.

Additionally, RapidAPI and RapidAPI for Teams can facilitate API collaboration. They do this by providing the collaboration space and tools that help the API producers document the specifications for their API.

In the next sections, we are going to examine these tools and I will provide examples of how we can use them for collaboration.

To access the API collaboration tools, you need to sign up for RapidAPI for Teams. Visit RapidAPI and select Create Organization in the navigation bar. It’s free to create an organization!

After creating your organization, visit the Organization Dashboard. You can explore the side navigation or learn more about each tab in the complete dashboard tutorial.

Team API Collaboration

Producers

If you are using RapidAPI for Teams to create APIs you are going to need to add teams and users. Using the top navigation, make sure that you are on your Organization Dashboard.

Here, you can manage teams and users by selecting the corresponding button on the side navigation.

A default team was added for you when you created the organization. However, if you wanted to invite more users to the organization, you can do this from the Manage Users tab.

You can add users manually, which allows you to categorize them in the dashboard and select what team they are apart of, or you can use bulk user imports from Github or a CSV file.

You can organize users by the teams they belong to or by the API they are allowed to access. Here, you are setting up the producer side of the API collaboration. Producers can manage/edit the documentation, view usage, and interact with consumers.

Creating a Mock API

Next, let’s set-up a mock API. The mock API is useful in the API-First design approach to provide an API that returns sample data. One of the advantages of this approach is that different teams (or API consumers) can know the data structures and routes that will exist later. For example, this can allow a front-end team to start work immediately without having to wait for the backend developers to code out all the routes.

In the previous example, the front-end developers represent the consumers, and the backend developers are the producers. We will have a collaboration space after we create the mock API.

Add Endpoint

Select My APIs in the top navigation bar.

Enter the API information into the form. In this example, we are going to use the user interface (UI) to create the API specifications. However, you could use OpenAPI, PostmanCollction, or GraqhQL Schema files if you have those available.

After you add the API, you can always upload a different file later on the Definition navigation tab under the API.

On the Definition tab, underneath the newly created API, there is a secondary navigation bar at the top of the page. Select Endpoints to add a new endpoint.

Then, choose to Create REST Endpoint.

Create a fake endpoint, making sure to fill out the required information.

This is also the place the enter external documentation for routes. For example, a Github README file.

Add parameters to the endpoints. Ideally, these would be parameters that the stakeholders in the API had agreed on in the design.

Next, Scroll further down the page and notice that we have the option to create a Mock Response.

Create a mock response that represents the data response that anyone consuming the API should expect. Remember, since this uses an API-First approach there is no code yet. The API will not do any calculations when mocking is enabled. It will only return the example response with the example response code.

Be sure to toggle Enable Mock Response and then Save the information.

Add Base URL

Enter an example base URL to the API.

Add Image

Add an example image to display with the API.

Publish the Mock API

At this point, you have entered the specifications and set up mock responses for all the routes in the API. Next, we want to publish the API so producers and consumers can start building.

This is also a good place to invite more developers to have access to the API so they can collaborate.

Toggle the Private button to publish the API.

Test the Mock API in the Marketplace

On the API page towards the top right of the window select the option to View in Marketplace

This will take you to the API dashboard of your new API. This is what other developers will see when they view your API.

Next, select the Categorization endpoint and hit the Test Endpoint button. Our mock response appears on the results tab.

Community Discussion

We now have an API that returns mock responses that helps guide producers and consumers in the collaboration process.

But, the two groups need to be able to communicate on the API. Furthermore, there is a high chance that questions arise from the consumer side.

On the API dashboard page, users can submit community discussion questions or directly message the providers.

Public discussions will show up here that can help answer common questions.

The API developers, or other team members, can view and respond to user questions on the private API page. Back on My APIs page, select Support on your API dropdown.

If a specific user has a question about their API requests you can view the requests that they have been making by selecting the Users tab on the API dropdown.

On RapidAPI, teams can create community discussions, exchange private messages, and provide documentation. This creates an effective collaboration space between the API’s stakeholders.

Updating API Specifications

Over the lifecycle of your API, there will be changes to the documentation and endpoints. RapidAPI exposes an endpoint that accepts an API specification file that allows you to update your documentation use continuous integration (CI) and continuous deployment (CD).

You can view the API endpoint by following the link on your API Definition page. Remember to grab the API ID.

This can open the door to faster API collaboration if the iterations pick up speed, or if any of the endpoint specifications change substantially.

Announcements

Send an email announcement to all users of this API to inform them about new features, bug fixes, pricing changes or other updates.

Users can also make announcements to their community of users from the API Definition tab. Towards the top of the page on the secondary navigation bar select the Announcements tab. Then click the Send New Announcement button.

Communication is king in API collaboration and being able to quickly send announcements helps make it easier.

Conclusion

In this article, we talked about API collaboration and some of the key considerations when developing an API.

• Choose your design approach. Will you go with a Code-First or API-First approach?

If you choose to go with the API-First approach, we learned that you can easily set up specifications on RapidAPI for Teams and invite developers to collaborate from Github or by importing a CSV file.

Furthermore, you can quickly set up mock APIs so one team’s work does not slow down others.

• Who are the consumers and producers?

Record all the stakeholders that are going to be a part of the collaboration process.

• How are consumers and producers going to collaborate?

Design an appropriate collaboration space that facilitates communication. On RapidAPI, this was the community discussion board, private messages, and user announcements.

• How can we maintain a healthy collaboration space as the API moves through its lifecycle?

Documentation can be updated directly in the dashboard, which lives next to the community discussions. Furthermore, teams can set up CI/CD to automatically update the API specs when the API changes.

I hope this introduction to API collaboration has put your mind at ease and you are ready to start designing your next API!

FAQ