REST APIs (GQL PAPI)

Create an API

Create an API "from scratch"

In the left frame of the playground, scroll up and click Root. Expand the Mutations dropdown. Since we are going to add an API to the Hub, we are mutating (changing) data rather than querying existing data.
Click createApi (you can search for it if needed). You should see the fields that you can specify when creating an API. Also notice that an api argument must be specified when creating an API.
Add the following to GQL Query:

mutation createApi($apiCreateInput: ApiCreateInput!) {
  createApi(api: $apiCreateInput) {
    id
  }
}

📘
Mutation input arguments are discussed here.

Below GQL Query, click Variables and enter the following to create a REST API:

{
  "apiCreateInput": {
     "name": "My REST example",
     "category": "Other",
     "description": "REST API example.",
     "version": {
        "name": "1.0"
     }
  }
}

In the middle frame, verify that you are using your Personal Account context.
Click Test Endpoint. An API should have been created and you should see the new API's id in the Results. Notice that the mutation operation requested that the id is returned from the call to createApi. Copy the id and paste it somewhere handy so that you can use it in the updateAPI operation below.

📘
Creating an API in a team context
To create an API in a team context, you must include the x-rapidapi-identity-key header parameter. This is used to identify the user creating the API, and to verify that they have the permission to create the API. The value of this header parameter is an app key from your Personal Account. You can obtain this key by selecting your Personal Account when testing any API’s endpoint and copying the X-RapidAPI-Key header parameter value.
See GraphQL Platform API Authorization for more information.

Verify that you can see your API in Studio (My APIs). You also should be able to search for it from the API Hub.

Update an API

📘
Permissions to update a team's API
To update a team's API, make sure that the x-rapidapi-key for the team that owns the API that you want to modify is used in the mutation. The x-rapidapi-identity-key must be the personal account x-rapidapi-key for a member of the team. One way to make this work is if the user calling the GQL Platform API is an org admin in the organization. They are automatically members of every team.
Additionally, the team that owns the API to be modified must have access to the GraphQL Platform API. You can achieve this by making the GraphQL Platform API public, or by inviting the organization that contains the team that owns the API to use the GraphQL Platform API. In Provider Dashboard: GraphQL Platform API > Definition > Global Settings > Invite Developers. In RapidAPI Studio: GraphQL Platform API > Hub Listing > Community > Invite Users.

In the left frame of the playground, scroll up and click Root. Expand the Mutations dropdown.
Click updateApi (or search for it). You should see the fields that you can specify when updating an API. Also notice that an api argument must be specified when updating an API.
Add the following to GQL Query:

mutation updateApi($api: ApiUpdateInput!) {
   updateApi(api: $api) {
     name
     category
     id
     termsOfService {
        text
     }
   }
}

Below GQL Query, click Variables and enter the following (paste the API id that you copied when creating the API.). You may need to change the category name to one that exists in your Enterprise Hub.

{
  "api": {
    "id": "[your API id]",
    "category": "Data",
    "termsOfService": {
      "text": "https://example.com/tos"
    }
  }
}

💡 This mutation changes the API's category and terms of service. The response contains the API's name, category, id, and termsOfService.

In the middle frame, verify that you are using your Personal Account context.
Click Test Endpoint. The API's category should have been updated and you should see the new category name in the results.
Verify that your API now has the new category name and terms of service/use (in the API's hub listing About tab.

Update an API's Base URL

To update an API's Base URL, you must know the target group ID for the version of the API that you want to update. This can be obtained using query.api, as shown above.

Once you have obtained the target group ID, you can execute mutation.updateTargetGroups:

mutation ($updates: TargetGroupUpdateInput!) {
  updateTargetGroups (
    targetGroups: [$updates]
  ) {
    id
    loadBalancingStrategy
    name
    targetUrls {
      url
      loadBalancingStrategyValue
    }
  }
}

{
  "updates": {
    "id": "targetgroup_[YOUR ID]",
    "targetUrls": [
      {
        "url": "https://[NEW BASE URL]"
      }
    ]
  }
}

Create an API from an OAS document

This mutation creates an API from an OpenAPI 3.x specification document for an API. The OAS document includes RapidAPI's OAS extensions. See Adding and Updating OpenAPI Documents for more information on RapidAPI's OAS extensions.

Uploading of OAS documents is an asynchronous process. Monitoring for progress and completion of ongoing imports is done separately by polling the apiSpecImportProgresses query using the tracking ID that this mutation returns.

The OAS file provided under spec may be in either JSON or YAML format.

Using the API Hub to create an API and upload an OAS file

The API Hub playground allows you to select a local OAS document to test the createApisFromRapidOas mutation:

In the API Hub, search for your GraphQL Platform API and click the Endpoints tab (see screenshot above).
In the center column, select the context that will own the new API. If this is a team context, you must also specify a value for the x-rapidapi-identity-key header. See GraphQL Platform API Authorization for more information.
Search for "oas" in the GraphQL schema using the search text box in the left column.
Hover over Mutation.createApisFromRapidOas and select Add Query.

After clicking Add Query, scroll down in the center frame and notice the Files section (see the screenshot above). Click Select File and select your local OAS document to upload. Note: This file must contain an info.x-category field. See Adding and Updating OpenAPI Documents for more information on RapidAPI's OAS extensions. The textbox to the left of Select File should contain creations.spec.

Click Test Endpoint. You should receive a 200 status. In the response, you should see the new apiId, the trackingID to track file upload progress and any warnings related to the file upload. See the screenshot above.

Creating an API and uploading an OAS file programmatically

mutation createApisFromRapidOas($creations: [ApiCreateFromRapidOasInput!]!) {
  createApisFromRapidOas(creations: $creations) {
    apiId
    trackingId
    warnings {
      type
      critical
      text
      info
    }
  }
}

{
  "creations": "[ApiCreateFromRapidOasInput!]!"
}

Here is a sample Node.js file that creates a REST API by uploading an OAS file with RapidAPI extensions. A multipart HTML form is used to upload file and to specify the GraphQL mutation and variables.

If a team will own the API, specify the team's X-RapidAPI-Key in the header. If your personal account will own the API, specify your personal X-RapidAPI-Key in the header.

const FILENAME = '[YOUR FILE NAME]';
const axios = require("axios");
const FormData = require('form-data');
const fs = require('fs');

let file = fs.readFileSync(FILENAME);

// OPTIONALLY MODIFY OAS DOCUMENT HERE
file = JSON.parse(file);
file.info['title'] += new Date().toLocaleString().replace(",", "");
if (!file.info['x-category']) file.info['x-category'] = 'Other';
file = JSON.stringify(file);

const query = `
  mutation createApisFromRapidOas($creations: [ApiCreateFromRapidOasInput!]!) {
    createApisFromRapidOas(creations: $creations) {
      apiId
      trackingId
      warnings {
        type
        critical
        text
        info
      }
    }
  }`;

const variables = {
  creations: {
    spec: null // As dictated by the GraphQL upload specification, this null `spec` prop is intended as a mere placeholder while the ACTUAL file may be passed/streamed independently as a consequent multipart field as seen below.
  }
};

const formData = new FormData();
formData.append('operations', JSON.stringify({ query, variables }));
formData.append('map', '{"0":["variables.creations.spec"]}');
formData.append('0', file, FILENAME);

const options = {
  method: 'POST',
  url: '[YOUR URL FROM SAMPLE CODE]',
  headers: {
      ...formData.getHeaders(),
      'x-rapidapi-identity-key': '[YOUR PERSONAL KEY]',
      'X-RapidAPI-Key': '[YOUR PERSONAL OR TEAM KEY FROM SAMPLE CODE]',
      'X-RapidAPI-Host': '[YOUR HOST FROM SAMPLE CODE]'
  },
  data: formData,
};

axios.request(options).then(response => {
   console.log(JSON.stringify(response.data));
}).catch(error => {
    console.error(error.response.data);
});

Update an API from an OAS document

This mutation updates an API from an OpenAPI 3.x specification document for an API. See Adding and Updating OpenAPI Documents for more information on RapidAPI's OAS extensions.

In the variables, you must specify the apiVersionId for the version of the API that you want to update.

mutation updateApisFromRapidOas($updates: [ApiUpdateFromRapidOasInput!]!) {
  updateApisFromRapidOas(updates: $updates) {
    apiId
    trackingId
    warnings {
      type
      critical
      text
      info
    }
  }
}

{
  "updates": {
    "spec": null,
    "apiVersionId": "apiversion_abcd"
  }
}

You can upload a local copy of your OAS document using the Files area in the API playground, as shown below:

Here is Node.js sample code for the updateApisFromRapidOas mutation:

const FILENAME = '[YOUR FILE NAME]';
const axios = require("axios");
const FormData = require('form-data');
const fs = require('fs');

let file = fs.readFileSync(FILENAME);

// OPTIONALLY MODIFY OAS DOCUMENT HERE
file = JSON.parse(file);
if (!file.info['x-category']) file.info['x-category'] = 'Other';
file = JSON.stringify(file);

const query = `
mutation updateApisFromRapidOas($updates: [ApiUpdateFromRapidOasInput!]!) {
  updateApisFromRapidOas(updates: $updates) {
    apiId
    trackingId
    warnings {
      type
      critical
      text
      info
    }
  }
}`;

const variables = {
  "updates": {
    "spec": null,
    "apiVersionId": "apiversion_[YOUR API's VERSION ID]"
  }
};

const formData = new FormData();
formData.append('operations', JSON.stringify({ query, variables }));
formData.append('map', '{"0":["variables.updates.spec"]}');
formData.append('0', file, FILENAME);

const options = {
  method: 'POST',
  url: 'https://graphql-platform1.p.rapidapi.com/',
  headers: {
      ...formData.getHeaders(),
      'x-rapidapi-identity-key': '[YOUR PERSONAL KEY]',
      'X-RapidAPI-Key': '[YOUR PERSONAL OR TEAM KEY FROM SAMPLE CODE]',
      'X-RapidAPI-Host': '[YOUR HOST FROM SAMPLE CODE]'
  },
  data: formData,
};

axios.request(options).then(response => {
   console.log(JSON.stringify(response.data));
}).catch(error => {
    console.error(error.response.data);
});

Delete an API

In the left frame of the playground, scroll up and click Root. Expand the Mutations dropdown.
Click deleteApi (you can search for it). Notice that an id argument must be specified when deleting an API.
In the left frame, click Root. Under Mutations, hover over deleteAPI and click ADD QUERY. You should see information filled in under GQL Query and variables.

💡 You can use the ADD QUERY button here because the query is quite simple.

In Variables, replace ID with the value for the API that you created above.

mutation deleteApi($id: ID!) {
  deleteApi(id: $id)
}

{
  "id": "ID"
}

In the middle frame, verify that you are using your Personal Account context.
Click Test Endpoint. You should see that the API has been deleted.
In Studio (My APIs), verify that your API has been deleted.