GET /v1/document/share — ReportingCloud

GET https://api.reporting.cloud/v1/document/share

Description

Returns an encrypted name for a document in the template storage, which the viewer widget of ReportingCloud takes to display that document in a web page. The name in templateName is matched regardless of case, and the same name gets the same encrypted name on every call. This method doesn't count against a quota. See Sharing Documents.

Examples

Request:

curl -u username:password \
  -X GET "https://api.reporting.cloud/v1/document/share?templateName=test.doc"

Results:

"jHjsdfhsdfjhaJhJHSF-HFhjusefhJH787fha-ahjasdhuzhKLJHLLKUjhdfadf8988"

Request:

using System;

TXTextControl.ReportingCloud.ReportingCloud rc = new TXTextControl.ReportingCloud.ReportingCloud("username", "password");
var templates = rc.ListTemplates();
var hash = rc.ShareDocument(templates[0].TemplateName);
Console.WriteLine(hash);

Results:

jHjsdfhsdfjhaJhJHSF-HFhjusefhJH787fha-ahjasdhuzhKLJHLLKUjhdfadf8988

// Example code coming soon.

# Example code coming soon.

Request:

<?php

require_once __DIR__ . '/vendor/autoload.php';

use TextControl\ReportingCloud\ReportingCloud;

$reportingCloud = new ReportingCloud([
    'api_key' => (string) getenv('REPORTINGCLOUD_API_KEY'),
]);

$response = $reportingCloud->getClient()->request('GET', '/v1/document/share', [
    'query' => [
        'templateName' => 'test.doc',
    ],
]);

var_dump(json_decode((string) $response->getBody()));

Results:

string(67) "jHjsdfhsdfjhaJhJHSF-HFhjusefhJH787fha-ahjasdhuzhKLJHLLKUjhdfadf8988"

The PHP SDK has no method for this endpoint, so the sample sends the request with the SDK's HTTP client, getClient(), which carries the authorization and the base URL.

Authorization

This endpoint requires a "ReportingCloud-APIKey" or a "Basic" user authorization to access the user account, data and templates. Only one of these two methods is required.

API Keys describes how to create an API key, and Authentication explains both header forms.

ReportingCloud-APIKey

Header field	Description
Authorization	Required. A valid ReportingCloud account is required. The Authorization field is constructed as follows: An API key needs to be generated in the portal or with PUT /v1/account/apikey. The authorization method and a space, "ReportingCloud-APIKey ", is then put before the actual API key string. For example: `Authorization: ReportingCloud-APIKey oMDM4MrAqL9QEOpyzupnQW5NjvCNtvE5cVDaaLqxI`

Basic

Header field Description

Authorization Required. A valid ReportingCloud account is required. The Authorization field is constructed as follows: The user name and password are combined into a string separated by a colon, for example username:password. The resulting string is encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line. The authorization method and a space, "Basic ", is then put before the encoded string. For example: Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

Header field	Description
Authorization	Required. A valid ReportingCloud account is required. The Authorization field is constructed as follows: The user name and password are combined into a string separated by a colon, for example `username:password`. The resulting string is encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line. The authorization method and a space, "Basic ", is then put before the encoded string. For example: `Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l`

Request Parameters

Name	Type	Value	Optional
templateName	String	The filename of the template in the template storage, with its extension. The name is matched without regard to case, and the encrypted name encodes it as it is written, so that two spellings of one name give two encrypted names. Without templateName, or with an empty value, the request isn't refused: the response is an encrypted name that names no template.	no

Success Response

Status	Description
200	On success, the HTTP status code in the response header is 200 (OK). The response body contains a JSON string that represents the encrypted document name, of letters, digits, "-" and "_". The same template name always returns the same encrypted name, whichever authorization method the request uses.

Error Response

Status	Description
400	A 400 (Bad Request) with the plain text "Template doesn't exist in storage" is returned, if the template doesn't exist in the template storage.
403	A 403 (Forbidden) is returned, if the user is not authorized.
405	A 405 (Method Not Allowed) is returned, if the request uses another HTTP method than GET. The Allow header of the response names GET.
500	A 500 (Internal Server Error) is returned, if the request has no Authorization header, an empty one or one that is not the authorization method, a space and the credentials.