Skip to main content

OpenAPI

You can add any OpenAPI-compliant API as a service in TakeShape. The OpenAPI service allows TakeShape to read the specification of the API you're using, and generate a custom schema with its queries and mutations.

Connecting an OpenAPI service requires you to know the endpoint you're connecting to and any authentication requirements it has.

In the following walkthrough, we'll be using the Pet Store API from swagger.io.

Connect an OpenAPI service​

Start by going to your project's schema tab. Then, select Connect Service in the top right corner. You'll see a new page with multiple services you can choose from. Select OpenAPI.

In this example, we'll connect the Pet Store API. Enter a simple Name and Slug for your service. You may optionally set a Namespace, which will add a prefix to the types and queries generated in your schema.

Next, set your Endpoint to the API endpoint. In this case, it's https://petstore.swagger.io/v2. Next you'll set your Spec, which is a URL to your chosen service's OpenAPI specification. In our case, the url is https://petstore.swagger.io/v2/swagger.json. A url to your service's specification may be found in its documentation.

The final setting is the Authentication Type. If no authentication is required, choose None, then select the Save button. Otherwise, there are several options:

Bearer Token​

Bearer Token authentication is the most common authentication method for OpenAPI services. Most API authentication systems require a header similar to:

"Authorization": "Bearer Your-Token-Here"

When setting Bearer Token authentication for an OpenAPI service, the Header value should be set to the header property that is used for authentication. When this field is left blank, this value will default to Authorization. However, if your service uses a different header, for example "api-key", then you should input api-key as the value.

The second Header value is the text that will be prepended to the start of your token. If left blank, the header value will default to Bearer as the first word in the value of the authentication header. If your API uses an alternative, input that alternative into the second Header field.

The Token is your API access token, which will need to be provided by the API you're connecting.

Query Parameter​

When using Query Parameter authentication, the Query Param and Token values will be appended as a query string parameter to the APIs URL. For example, if you set the Query Param to testParam and the Token to testValue, requests to your url endpoint will look something like this:

https://example-endpoint/api?testParam=testValue

Basic Auth​

When using Basic Auth authentication, add your username and password to the appropriate fields. They will be joined into a colon-delimited string, like username:password. Some APIs don't require a username; in this case, leave the field blank to get a colon-prefixed password string.

When your service is fully configured, select Save.

As long as your service is correctly configured, you'll be provided with the option to select queries and mutations from the OpenAPI service to add to your TakeShape schema.

Selecting Queries & Mutations​

With the power of TakeShape, you can import any query or mutation from your OpenAPI specification to your schema. Instead of having to manually write queries and mutations, you can create them with a few selects.

A dialog to select queries and mutations you'd like to add will be shown after connecting a service for the first time. To re-open the dialog later, visit the connected service's page and select the button labeled Select OpenAPI Queries/Mutations.

Once your specification has loaded, the dialog will disappear and you will be shown all the queries and mutations you can import. If your spec fails to load, you will be taken back to your project page.

If the spec fails to load, please check that the url to the specification file is correct. If it is, ensure that your authentication setup is compatible with the API you are using. For example, if your API requires Basic Auth, ensure that you haven't set it to Query Parameter. If all else fails, feel free to ask for help.

Adding Queries and Mutations to Your schema​

Once your specification has been processed, TakeShape will show you a list of all queries and mutations it's capable of importing, organized into a table. The Type column tells you whether it's a Query or Mutation. The Name column tells you the name it will have, which will be prefixed by the Namespace, if you provided it in your service setup page as described above..

Use the checkboxes on the left to select which queries and mutations you want to import, and then select Save in the bottom right. Otherwise select Skip.

After you select Save, the menu will disappear, and you will be back on your project summary page. If you scroll down to the Queries and Mutations table on this page, you will see your new imports listed.

You can also select on the JSON tab to view your schema directly. Scroll down to the "queries" property, and you will find your queries laid out as described in your specification.

In the same JSON tab, scroll down further to the "mutations" field. You will see your mutations also perfectly implemented.

Manually adding Queries and Mutations to your schema​

Because you're using OpenAPI, queries and mutations should be importable through the TakeShape web interface thanks to the APIs specification. If this is impossible, you will have to manually write your queries and mutations into your JSON file.

We have already detailed this process here.

Schema options​

When editing a schema with an OpenAPI service present you can add the useRestfulNames option to the schema to generate more user-friendly query names from the OpenAPI spec.

For instance, here's a Stripe service, with the option added:

{
  "stripe": {
    "id": "stripe",
    "provider": "stripe",
    "title": "Stripe",
    "namespace": "Stripe",
    "serviceType": "openapi",
    "authenticationType": "bearer",
    "authentication": "abcdefg",
    "options": {
      "endpoint": "https://api.stripe.com/",
      "spec": "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json",
      "useRestfulNames": true
    }
  }
}

Without this option your query selection screen would generate the following query names for operations to list customers and get a single customer:

  • List Customers - Stripe_GetCustomers
  • Get Customer - Stripe_GetCustomersCustomer

With the option enabled, you'd instead have these queries generated:

  • List Customers - Stripe_listCustomers
  • Get Customer - Stripe_getCustomer

Still need help? Get in touch with us.