Say Hello to Vectara’s “API Playground”
Hello Vectara users!
We wanted to announce a few key developer-focused features that are now ready for you to try and provide us with more feedback! Some of these are the most requested features by our community, so we’re happy to be able to deliver them!
March 07 , 2023 by Shane Connelly
Indexing API Keys
API keys are almost always the easiest way to get started with an API-focused product: you plug an API key into a request and you’re set! However, up until now, Vectara’s API keys have been focused on query usage. This has been for a few reasons. The most important has been that granting “write” access to an account adds a level of risk that not everyone appreciates: API keys and other secrets often get “lost” into public git commits or public webpages. So we wanted to make sure to seriously consider the security model as well as the user/developer experience before we rolled out API keys for indexing.
But now the wait is over! API keys for indexing are here! To create a new API key, you follow the same flow of going to your API keys in the console, where you can create a new key:
To create an API key that can both index and query, select the second toggle to include both QueryService and IndexService. Do be careful to protect your API keys – especially any that you’ve used for indexing. We’ve restricted these keys to not have account-level permissions and allowed you to specify which corpora they should be able to interact with, but be careful to protect them as you would a password.
OpenAPI Specification and API Playground
We’ve heard from a number of you that you want a better way to build and test your applications on top of Vectara using tools you’re already familiar with. To that end, we’ve released an OpenAPI specification as well as an API playground within our documentation to give you copy-paste access to developing and using the Vectara APIs. Here’s how it works:
You can always grab the latest version of our OpenAPI specs now at https://docs.vectara.com/vectara-oas.yaml. You can use these API tooling of your choice, for example, Postman, Insomnia, and so on, to drop this spec in and start playing around with the Vectara APIs:
And if you’d like to get started playing around with the APIs without installing any tools at all, we’ve now launched a REST playground within our documentation. For example, let’s say you wanted to learn how to index documents: head on over to the Index API playground where you’ll find the index API. Add an Indexing API key or an OAuth 2.0 bearer token into the authentication section, fill out your customer ID and a JSON entry, remove any JSON body elements you don’t wish to make use of (e.g. custom dimensions or metadataJson if these don’t apply to you), and select the “Send API Request” to test the API request and response:
You can see what all of the parameters do on the left-hand side, and if you scroll down, you’ll find you can copy/paste client code in a language of your choice after you’ve nailed down what the request format and data should look like:
Copy and paste this to your favorite IDE to kickstart your application development on top of Vectara!
As always, we’d love any feedback and additional feature requests! Head on over to our forums to chat with us more!