Slingshot

This is the documentation for the main page in Slingshot.

Making a request

You make requests using the Slingshot request editor which is front-and-center on the main page. There you have the possibility to pick HTTP method, type in a URL, add parameters, headers, body payload and a lot more.

When you start the app, you can hit Send the first thing you do. If the URL bar is empty, it will default making a request to https://requestbite.com/hello which returns a friendly example response in JSON format.

The best way to learn how the request editor works is by playing around with different URLs and settings and hitting Send to see what the result will be.

Adding path parameters

Path parameters are added under the Params tab.

They are mostly of interest when your request is saved in a collection and refer to a part of the URL path that can be swapped out based on a variable.

Let's say you have a URL that looks like this:

example.com/items/123

... where 123 is a variable that represents an item. Then 123 can be replaced with a path parameter called e.g. id like so:

example.com/items/:id

Any part of a path that starts with a colon (e.g. :key) becomes a path parameter and will show up like follows under the Params tab in the request editor:

[x] [ key     ] [ value      ]

If you import an OpenAPI spec or a Postman collection (in which path parameters are denoted as {variable}), they will be converted to :variable to work as path parameters in Slingshot.

If you do not provide a value for a path parameter, the name of the path parameter name will be sent verbatim to the target server. You can choose not to send a value for the path parameter either by unticking the checkbox to the left of the path parameter, or by leaving the value part of the path parameter empty.

Adding query parameters

Query parameters are added in the URL bar and show up under the Params tab.

Query parameters are added directly in the URL barlike so:

example.com/items?page=3&limit=10

When added as in the example above, the following fields show up under the Params tab:

[x] [ page     ] [ 3        ]
[x] [ limit    ] [ 10       ]

It's not possible to edit the query parameters under the Params tab (which you do directly in the URL bar), but just like for path parameters, it's possible to disable a query parameter by unticking the checkbox next to it.

Slingshot makes sure the formatting of the query parameters are correct, regardless of whether a query parameter is enabled or not. I.e. if your URL bar looks like so:

example.com/items?page=3&limit=10

... and you untick the checkbox for ?page=3, then Slingshot will automatically reformat the URL to look like this when sending:

example.com?limit=10

Adding headers

Request headers are added under the Headers tab.

To add a request header, open the Headers tab and click the blue + button. Then all you need to provide is a header name and a value.

If you do not provide both a header name and a value, the header will not be included in the request. Just as with path and query parameters, you can also opt to not send a specified header by unticking the checkbox to the left of it.

Default headers

The following headers are added by default when sending a request:

Host
This is set to hostname from the URL bar and cannot be overridden.
User-Agent
By default this is set to the user-agent string of the Slingshot proxy, but can be overridden by providing a custom value.
Accept-Encoding
By default this is set to gzip but can be overridden by providing a custom value.

Additional headers can also be automatically set depending on HTTP type. Examples include Content-Length, Accept and Content-Type.

Adding request body

A request body can be added under the Body tab.

The following HTTP methods accept a request body:

POST
PUT
PATCH
DELETE

If you pick any other HTTP method the Body tab becomes inactive and any previously provided body payload will be disabled.

Raw

This is probably the most common body type for e.g. REST APIs as this option is used for sending e.g. JSON or XML payloads.

When picking Raw, you get to pick the following subtypes:

JSON

Picking JSON will automatically add a Content-Type: application/json header to the request. It will also allow you to prettify (format) your JSON payload and will warn you if the JSON content is invalid. Any JSON you add will be automatically syntax-highlighted.

XML

Picking XML will automatically add a Content-Type: application/xml header to the request but no additional functionality or syntax highlighting is currently supported.

Text

Picking Text will automatically add a Content-Type: text/plain header to the request but no additional functionality or syntax highlighting is currently supported.

multipart/form-data

This creates a multipart/form-data form submission and allows you to send either text-based key-value pairs or binary files. This is generally the type of body payload used for HTML forms that include file uploads. Picking this option will automatically add a Content-Type: multipart/formdata header with a proper boundary value to the request.

To add a form-data key-value pair, click the + Add button, select Text or File in the dropdown and provide the key-value data. If you picked File in the dropdown, you can provide a name for the file field and then pick a file to submit.

Just like for parameters and headers, you can disable sending any of the key-value pairs by unticking the checkbox to the left of it.

x-www-form-urlencode

This creates an application/x-www-form-urlencode form submission and allows you to send text-based key-value pairs. This is the default HTML form encoding when not including file uploads. Picking this option will automatically add a Content-Type: application/x-www-form-urlencode header to the request.

To add a form key-value pair, click the + Add button and provide the key-value data. Just like for parameters and headers, you can disable sending any of the key-value pairs by unticking the checkbox to the left of it.

Variables and secrets in requests

Collections and environments have the ability to store variables and secrets respectively. If your request is stored in a collection and/or uses an environment, you can use any such variable or secret in the request editor.

Let's say you import an OpenAPI spec into Slingshot. When doing so, Slingshot will automatically create a variable in the created collection called baseUrl that it sets to the base URL of the imported API. Also, each request will be prefixed with it like so:

{{baseUrl}}/items/:id

This means that if you want to update the base URL for the imported API, you only have to update the variable in the collection, not each and every request. This is also practical if you want to use the same collection but have different environments configured e.g. for your staging and production environments.

Variables and secrets can be used in any of the input fields in the request editor. All you need to do is type {{ in any of the input fields and it will automatically list any available variable or secret in a dropdown. Pick the value you want to use and it will be automatically added.

Any available variable or secret will show up in green. If the system cannot find your selected variable or secret, it will be highlighted in red.

If you send a request with a red variable, e.g. example.com/{{variable}}, the string {{variable}} will not be updated and will instead be sent as-is.

Enabling authentication

From the point of view of an HTTP request, authentication generally means providing a token or a set of credentials in a header, so it's of course entirely possible to provide the authentication details you need using the request editor directly.

But - to handle more advanced scenarios such as configuring Slingshot to be a proper OAuth or OpenID Connect client and making sure your credentials are stored securely, Slingshot environments have functionality for exactly this and makes sure credentials are properly encrypted in your browser.

Please learn more in the section What are environments?

When you have picked an environment in the sidebar, any configured authentication mechanism shows up in green text next to the Copy request button so that it's clear that authentication details will be added to your requests.

Request settings

If you do not have a collection picked in the sidebar, the request editor has an additional tab called Settings that you can use. It allows you to configure the following settings:

Automatically follow redirects
Set request timeout

If you're using a request in a collection, these settings are set in the collection's settings page.

What are collections?

Collections are named groups of HTTP requests that all share the same request settings and variables. Collections are generally used to store all requests available in a specific API and are created automatically by Slingshot when you import an OpenAPI spec or a Postman collection.

Learn more about collections here.

What are environments?

APIs often exist in different versions, e.g. a staging version and a production version. Environments are used to cater to these differences. One collection (which most often maps to one API) can use multiple environments, e.g. one for the staging version and one for the production version with e.g. different authentication details for each.

When you've selected a collection in the sidebar, you have the ability to pick an associated environment. You can also click Make default next to it to make sure the picked environment is automatically selected when you pick the same collection next time.

Learn more about environments here.

Drafts vs saved requests

As soon as you make the slightest update to a saved request, Slingshot stores both the updated details and the original details in your browser. This is so that you can move around the app and not lose any updates.

This updated request is now considered a draft, and in the upper right corner of the request editor you will now see the following test:

Request has unsaved data (restore)  [ Update ] [ Save as ]

If you want to revert your changes, you can click the restore link. This will immediately drop your changes. If you want to store your updates to the existing request, you click Update. If you instead want to save your updates as a new request, then click Save as and follow the instructions.

Import OpenAPI or Postman collection

If you want to import an OpenAPI spec or Postman collection, you can click the Import button in the upper left corner. Select any of the following items:

Link..*
Pick this option if you have a URL to an existing OpenAPI spec of Postman collection.
OpenAPI spec...
Pick this option to upload an OpenAPI spec as a YAML or JSON file that you have stored on your computer.
Postman collection..
Pick this option to upload a Postman collection file that you have stored on your computer.

If you have the Chrome or Firefox browser extension for Slingshot installed, you can also right-click on a link that points to an OpenAPI spec of Postman collection and click Open link in Slingshot from the dropdown.

If you have a link to e.g. an OpenAPI spec at https://example.com/openapi.yaml you can import it directly by creating a URL like so (see below) and open it:

https://s.requestbite.com?import=https://example.com/openapi.yaml

Import cURL command

If you have a cURL command in your clipboard, you can easily import it into Slingshot by clicking the button Import cURL and pasting it into the modal dialog that shows up. Then click Import and the command will be properly added to the Slingshot request editor.

Export request as cURL command

If you have a request in Slingshot that you want to run in cURL, open the request in question and click the button <> to the right of the Send button. This will present the request in cURL format. Click the Copy button to copy it to your clipboard.

Please note that any variables or secrets used in the request will be resolved and added verbatim to the copied command (otherwise it wouldn't be possible for curl to use the resolved values).

Copy request

If you have a request that you want someone else to be able to test, you can just open it and click the Copy request button and follow the instructions.

Please note that just like when exporting a request as a cURL command, the copied request URL will contain any variables or secrets in plain-text from the copied request (otherwise it wouldn't be possible for the recipient to properly run the request).

The copied URL is completely self-contained and includes all request details as base64-encoded. When the recipient receives your URL, all they have to do is pasting it into their browser's URL bar and it will open Slingshot with the request editor correctly populated with your request details.

Copy response from request

If you want to copy the response payload to your clipboard, all you need to do is to click the Copy link in the upper right corner of the response area of the screen.

Presentation of response data

Data is presented a bit differently depending on its type:

`text/plain`

Text is presented as ... well, text. But by default Slingshot also parses most ANSI color code escape sequences, meaning text primarily targeting your terminal app will be automatically syntax-highlighted.

You can disable this functionality by unticking the checkbox called Parse ANSI color codes in text/plain responses in collection's settings.

You can see how this works by opening this request which properly parses the color codes from https://cheat.sh.

`text/html`

HTML responses will be rendered as a webpage preview by default. To see the actual HTML code, click the Code tab just above the preview.

`application/json`

JSON responses automatically pretty-printed and syntax-highlighted and the editor supports collapsing and expanding sections of the returned JSON document.

Other data

Other types of data is presented as plain-text.

Precedence of variables and secrets

Secrets (which can be used for variables) in environments always take precedence over variables in collections. This is so that you can create different environments e.g. for your development vs production environments and easily switch between the two.

Let's say you have picked a collection and an environment in the sidebar. Let's further say that both have a variable/secret called baseUrl. When you use this variable/secret in the request editor, it will always show and use the value from the environment.

If you later remove the baseUrl value from the environment, it will automatically use the value from the collection instead.

How requests are sent

Requests are automatically sent through a proxy to bypass any CORS restrictions that would have made most HTTP requests impossible if the would have been sent from your browser directly.

By default Slingshot uses our hosted proxy at https://p.slingshot.com. This can be seen by a blue banner called Slingshot proxy in the upper right corner of Slingshot. If you want to configure Slingshot to use another proxy, you can click this banner to get to the Slingshot settings page.

If you use a custom proxy (or host your own) the banner will be green and say Custom proxy: https://example.com where example.com is the URL of your custom proxy.