API Documentation

open

3 min read

Capture files that are available via the web can be linked directly to CloudShark using a simple URL. This open URL method makes it very easy to integrate CloudShark into existing systems by allowing users to embed CloudShark links directly into web pages, email, chats, trouble tickets, etc.

The open method works by first looking at the URL of file it is being asked to open. If that URL has already been previously imported into CloudShark, the same exact session containing any annotation, comments, tags, etc is retrieved and loaded. If the URL has never before been imported, then it is fetched and a new session is created.

In contrast to the View URL API Method - which creates a new session every time it is invoked - the open method is perfect for teams collaborating on capture files stored in an external web-accessible repository.

Usage

GET /api/v1/<token>/open?url=<absolute-url to open>

The open method requires both an API token be configured, as well as the url parameter be defined.

Examples

The open method is used much like the view URL. The most common usage is embedding links into other pages that reference capture files on a shared system. This allows users to open capture files and see any annotations, comments, tags, etc. added by other users.

Before

<a href='http://server/caps/myfile.cap'>Download myfile.cap</a>

After

<a href='https://www.cloudshark.org/api/v1/<token>/open?url=http://server/caps/myfile.cap'>Open myfile.cap in CloudShark</a>

Accessing URLs with HTTP Authentication

The open method can be used with URLs with basic or digest authentication. These credentials can be embedded directly in the url parameter.

https://www.cloudshark.org/api/v1/<token>/open?url=http://username:password@server/caps/myfile.cap

Notes

We strongly recommend that the API token used in this style be an authenticated token - meaning the user must be logged in to CloudShark prior to clicking on the new open link above. When creating the token, put a check in the box labeled “Must be logged in to use token”.

If the user clicking on the link is not logged in, they will be prompted to do so before CloudShark looks up the URL they are requesting. Once they log in, and the capture file they asked for is located, they will be redirected the existing decode session.

It is possible that the current user doesn’t have permission to view the requested decode session - in which case they will be prompted to log-in again as someone who has the appropriate access.

It is recommended that if you are making use of this method, that you only use this method when adding capture files to the appliance. If there is more than one decode session associated with the given URL, CloudShark will return the one that has been on the system the longest.