Cloud - Documentation
- Ladislav Petruš
This page contains details for the Jira Cloud version of the Base64 Attachment REST API. The Server and Datacenter version of this page is available here.
This plugin provides a REST API that allows upload of Base64 encoded attachments:
Direct - allows direct upload of Base64 encoded attachments where metadata are stored in URL
JSON - allows upload of Base64 encoded attachments where both attachment and metadata are stored in JSON structure
Configuration
Plugin configuration is available in “Manage Apps” section of Jira settings via the Configure button or via the Base64 Attachment Upload → Configuration sidebar menu:
The configuration page consists of multiple sections:
Token mananagement
Traffic
Available workers
Token management
Integrations utilizing Base64 REST API endpoints authenticate using Upload Authentication Tokens (UAT) which are managed in this section.
The following actions and information is available in this configuration section:
A list of UATs that can be used to call Base64 REST API endpoints.
The ability to generate UATs.
The ability to delete existing UATs.
The user can generate a new UAT either for the currently logged in user by clicking on button “Generate for current user”, or for another user by entering the user id in “User ID” field and clicking on button “Generate for user ID”.
The user id can be determined from the URL when the given user is viewing his profile page:
In the above example the user id is: 643abcdef232143f3123854a34f.
Once the user clicks on either of the generate buttons the Upload Authentication Token (UAT) will contain a new UAT:
The generated token is quite long and even though it spans multiple lines it should be passed to Base64 REST API as a single line string: eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJBbGFuYXRhIGEucy4iLCJzdWIiOiJCYXNlNjQgQ2xvdWQgVXBsb2FkIEF1dGhlbnRpY2F0aW9uIFRva2VuIiwidG9rZW4iOiJjOTc5N2JhYi05MzI2LTRjZjktYjc4MC0zOTgyMTdkYWUzNzEifQ.dy6FPwM7kQybzI9xHcbSbrvbYY-X9jQPeGEDrqVgNhPL3yCl3ekG47cagRl8I3u7yP-6urwO3_3yVzUTu5NwOg
Each UAT is available in its entirety only when generated, you will not be able to display it again in the Configuration UI!
Make sure you copy the entire UAT!
Store the UAT securely since it is used for authentication against the Base64 REST API!
Traffic
Each call to the Base64 REST API consumes allocated monthly traffic. The status of the plugin license is used to compute monthly traffic allocation for Base64 REST API calls. Once calls to Base64 REST API surpass this limit then no more attachments can be uploaded in the given month. Contact us if you need to upload more attachments than your monthly traffic allocation allows.
The “Traffic” section in the UI displays information about this month’s and previous month’s used traffic and traffic limit for the given month:
Current traffic limits are:
Trial - 100 MiB
Commercial - 100 GiB
Available workers
The “Available workers” workers section displays a list of available workers. Each worker is an instance of the Base64 REST API that can be used to upload attachments to your Jira instance. From this section you can access Swagger UI of the given worker instance:
REST Endpoints
REST endpoints are deployed on worker instances. You can access the list of available worker instances in the “Available workers” section of the Plugin configuration UI.
Each worker provides a Swagger UI instance that is always available at <worker-url>/swagger-ui/index.html .
Direct endpoint
POST /rest/1.0/direct/{issueIdOrKey}/{filename}/?uploadAuthenticationToken={UAT}
Allows direct upload of Base64 encoded attachments where metadata are stored in URL.
The URL can be parametrized as follows:
{issueIdOrKey} - path parameter that should be replaced with the issue id or key
{filename} - path parameter that should be replaced with filename that will be displayed in Jira
{UAT} - upload authentication token generated in “Token management” section of the plugin configuration.
Example:
URL | |
|---|---|
Method | POST |
Content Type (HTTP Header) | text/plain |
Body | SGVsbG8gd29ybGQhCg== |
JSON endpoint
POST /rest/1.0/json/
Allows upload of Base64 encoded attachments where both attachment and metadata are stored in a JSON structure.
The JSON structure included in the body can be parameterized as follows:
issueIdOrKey - required parameter, should be replaced with the issue id or key
base64EncodedData - required parameter, should contain base64 encoded attachment data
filename - required parameter, should be replaced with filename that will be displayed in Jira
uploadAuthenticationToken - upload authentication token generated in “Token management” section of the plugin configuration
Example:
URL | |
|---|---|
Method | POST |
Content Type (HTTP Header) | application/json |
Body | {
"issueKeyOrId": "DEMO-6",
"base64EncodedData": "SGVsbG8gd29ybGQhCg==",
"filename": "test.txt",
"uploadAuthenticationToken": "eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJBbGFuYXRhIGEucy4iLCJzdWIiOiJCYXNlNjQgQ2xvdWQgVXBsb2FkIEF1dGhlbnRpY2F0aW9uIFRva2VuIiwidG9rZW4iOiJjOTc5N2JhYi05MzI2LTRjZjktYjc4MC0zOTgyMTdkYWUzNzEifQ.dy6FPwM7kQybzI9xHcbSbrvbYY-X9jQPeGEDrqVgNhPL3yCl3ekG47cagRl8I3u7yP-6urwO3_3yVzUTu5NwOg"
} |
API Response
This chapter describes the structure of the response that is returned by all API endpoints.
Success
All endpoints respond with the JSON response that the target Jira instance provided.
Example:
[
{
"self": "https://<jira-instance-id>.atlassian.net/rest/api/3/attachment/10076",
"id": "10076",
"filename": "sample.txt",
"author": {
"self": "https://<jira-instance-id>.atlassian.net/rest/api/3/user?accountId=643abcdef232143f3123854a34f",
"accountId": "643abcdef232143f3123854a34f",
"avatarUrls": {
"48x48": "<avatar-url>",
"24x24": "<avatar-url>",
"16x16": "<avatar-url>",
"32x32": "<avatar-url>"
},
"displayName": "John Smith",
"active": true,
"timeZone": "Europe/Bratislava",
"accountType": "atlassian"
},
"created": "2023-09-14T15:00:49.796+0200",
"size": 4,
"content": "<content-url>"
}
]Error
All endpoints respond usually with a JSON response that will contain the following fields when the API request processing failed:
message - error message
The HTTP status code of an error response will be in the 4** or 5** range.
Example:
- 1 Configuration
- 1.1 Token management
- 1.2 Traffic
- 1.3 Available workers
- 2 REST Endpoints
- 2.1 Direct endpoint
- 2.2 JSON endpoint
- 2.3 API Response