RapidAPI Teams for sharing APIs
APIs are being used across many organizations today. They can be applied to separate data sources and the applications which use them. This article discusses sharing internal API documentation and testing APIs with your team. To do that we will walk through the following process:
1) Create an organization account in RapidAPI, and invite team members to join it
2) Create an internal API for use in your organization
3) Create documentation for the API and share with the team from one member account
4) Demonstrate how another member of the team can access the documentation
5) Show how a third member of the team can test the API using the auto-generated test interface
We will start with the basic assumption that you have a team. This team is working with an internal data source. This data source needs to be accessible by many members of the team. They could be in different departments of your company, for example. And the source of the data comes from a different department within the organization. The data owners want to provide access to the data within your organization. But they don’t want to allow you to cause database errors by accident.
Years ago I worked at Intel. Each factory generated several types of data used by many departments. There were many interfaces to access the data. Some interfaces allowed engineers to create custom database queries. Occasionally someone would run a poorly written query. These queries caused a database to run out of resources and stop responding. Creating a standard set of APIs for engineers could prevent those situations. That way the database queries would not change.
Step 1. Create an organization account in RapidAPI, and invite team members to join it
Creating an organization account using RapidAPI Teams is an easy process. Start by filling out a registration form. In the form, you specify an organization name and invite team members to it. Each invitation can be for an admin or developer account, with different privileges.
Once you create the organization (which is free for up to 5 members!) you will then go to a dashboard. There a modal will appear with some helpful prompts for what to do next:
While creating the organization you will add team members to it by email address. Those email accounts will then receive an invitation to join your organization:
Once they accept the invitation, they see a prompt to sign up for a free account with Rapid API. If they are already registered they can login.
Step 2. Create an internal API for use in your organization
The next step after you create your organization is to add an API. For this article, I created an organization called Words of the Wise. The team members will be adding new proverbs to Mongo DB supporting the Proverbs API.
To enable that capability we’ll add an internal API called “Add Proverb”. This API will allow team members to add new proverbs to the database. They can add proverbs without accessing the database. It will be a private API for use only by the “Words of the Wise” organization.
Step 3. Create documentation for the API and share with the team from one member account
Part of creating a new API is defining endpoints. The Rapid API interface allows you to create documentation for an API as you add it to your account. Once you create a team you have the choice to add an API as an individual or as a team:
When you add an API using your team account it will be accessible by all your team members. This is how you can share internal APIs within your organization.
For the “Add Proverb” api there will be one endpoint with two parameters. Since it is updating the database (adding a record) we will use a POST call instead of GET. The Endpoints page within the Definition area of the API has documentation. This specifies how the API interaction works.
I use a “Design First” approach for this API. That means I use the Rapid API interface to define the API before actually creating it. Or you could create the API code and then define it in Rapid API. That is an example of a “Code First” approach. Swagger has a good discussion of how those two approaches work and when to use each one.
The new internal API will interact with the same database as the Proverbs API. It will validate inputs, check for duplicates, and then add a new record. Here is the code:
<?php /* File: proverbs-add.php Description: This api takes 2 required inputs and validates them. It checks if the source is not in the array of allowed sources. Then it queries a local MongoDB collection to check for duplicates. If none are found a new record is added. Then a message is returned about whether a record was added or if there was a validation error. Inputs: proverb - new proverb to add source - source of new proverb Outputs: JSON object with the following field: message - either "Invalid Source", "Empty Proverb", "Proverb already exists", or "New Proverb added" */ global $debug; $debug=false; $apiKeyAllowed = [this key is from the security tab of the API]; $sourcesAllowed = ['proverbs','shakespeare','emerson','thoreau','rumi','tao te ching']; //Make sure this is a valid request, otherwise stop $headers = apache_request_headers(); if (empty($headers['X-Rapidapi-Proxy-Secret'])) { die(); } else if ($headers['X-Rapidapi-Proxy-Secret']!==$apiKeyAllowed) { die(); } else { //Collect Inputs $proverb = (!empty($_POST['proverb']))?$_POST['proverb']:''; $source = (!empty($_POST['source']))?$_POST['source']:''; //Validate source if (!in_array(strtolower($source),$sourcesAllowed)) { $message = "Invalid Source"; } //Check for empty value else if (empty($proverb)) { $message = "Empty Proverb"; } else { //Create query to check for existing proverb - we only need to escape double quotes // We use regex to check for an existing proverb which has a different case using the i option. $query = '{proverb: { $regex: /^'.str_replace('"','"',$proverb).'$/, $options: '-i'}}'; //Construct the command executed on the server $mongoCmd = "mongo proverbsdb --quiet --eval "printjson(db.proverbs.aggregate([{\$match: $query}, $sampleAggregate]).toArray())""; //This line can be used to make sure we are sending a valid command to Mongo if ($debug) echo "n mongoCmd is $mongoCmdn"; //Backtick notation executes the command as if it was typed in a console $proverbsJSON = `$mongoCmd`; $proverbsObj = json_decode($proverbsJSON); if (count($proverbsObj)>0) { if ($debug) print_r($proverbsObj); $message = "Proverb already exists"; } else { //Now we add the new proverb - escaping the double quotes again $query = "db.proverbs.insert({proverb:\"".str_replace('"','"',$proverb)."\", source:\"".$source."\"})"; $mongoCmd = "mongo proverbsdb --quiet --eval "printjson(".$query.")""; $writeResult = `$mongoCmd`; $resultObj = json_decode($writeResult); // Generate a message to send back if ($resultObj->nInserted>0) { $message = "New Proverb added"; } else if (!empty($resultObj->writeError)) { if ($debug) { $message = $resultObj->writeError->errmsg; } else { $message = "Database error, please try again later."; } } } } // end inputs validation //echo the response in JSON format $jsonObj = new stdClass(); $jsonObj->message = $message; echo json_encode($jsonObj); } // end of api key validation
Step 4. Demonstrate how another member of the team can access the documentation
Once the API is defined and added to the organization, another member of the team can then access the new API. When they log in to rapidapi.com they will see an Organization drop-down. This will be in the navigation or hamburger menu, depending on the screen width of the browser:
When they click the link they go to the Organization Homepage. Then they will see all the APIs created by the organization:
When they click on an internal API they will be taken to the Endpoints page for that API. Since they are part of the organization they also have a link next to the API category called “Edit API”. From there they can edit the endpoints, documentation, and other settings of the API.
Step 5. Show how a third member of the team can test the API using the auto-generated test interface
Once the API is saved in the Rapid API interface for the Organization, any member can then test it. First, they will log in to rapidapi.com, then go to their Organization Homepage. From there they will then click on an internal API. On the Endpoints view of the API, they can then enter parameters into the interface and test it. Here’s an example of a test of the new Add Proverb API:
Next: Learn how to track and monitor API Analytics & Usage
Conclusion
Setting up an Organization in Rapid API is an easy process. We’ve discussed sharing internal API documentation and testing APIs with your Team. Once you create an API from an Organization account, any other team member can access it. The team can share the documentation and testing of the API on their homepage. This works with both the “Design First” and “Code First” approaches. Rapid API team members can collaborate using an Organization account.
Using Rapid API Teams allows you to separate the development and testing of the APIs. One group of developers can be in charge of developing APIs. Another group can be in charge of testing them for different usage models. All this can use private APIs that people outside your team do not have access to.
In the Words of the Wise example Organization, I created a private API to populate data for a public API. On a large scale, there could be team members or internal services doing that. They would use an internal API to update the database for a public API.
Leave a Reply