I am writing an OpenAPI 3.0 specification and have an endpoint returning a file. Now I found documentation on the website of Swagger but that's about a POST request: https://swagger.io/docs/specification/describing-request-body/multipart-requests/.
There's also another StackOverflow question with zero responses about my question, so I will give it another go.
How does one write a specification for a GET request where a file should be returned?
I currently have the following:
responses:
'200':
description: ok
content:
multipart/form-data:
schema:
type: object
description: The multipart object containing the file bytes
properties:
file:
type: string
format: binary
description: Bytes of the file
But I think this is mostly for POST request, to upload a file. Does anyone know what it should be?
In OpenAPI 3.0, a response containing a PDF, PNG, or JPG file is described as follows:
responses:
'200':
description: A PDF file, PNG image, or JPG image
content:
application/pdf:
schema:
type: string
format: binary
image/png:
schema:
type: string
format: binary
image/jpeg: # 'jpeg' not 'jpg', see https://stackoverflow.com/q/33692835
schema:
type: string
format: binary
Related
I have some string parameters with specified format in my OpenAPI documentation.
email:
type: string
format: email
hostname:
type: string
format: hostname
path:
type: string
format: uri
I want to define maxLength to protect from harmful queries.
Do I have to do it or does format already define the maximum length?
For some of the formats the length of its value is defined. You can refer https://github.com/OAI/OpenAPI-Specification/issues/607#issue-142290879 to get the RFC definition for these formats. Apart from those if you think you need to have your predefined max/min length for the string value you can add them or you can use pattern keyword as well if you want to introduce any custom formats in your API definition. Using format has its own advantage and disadvantages.
Advantage
You can keep the API definition clean with few lines
You don't have to worry about the length if you want to follow a generally accepted lengths for your payload parameters.
Disadvantage
You have to stick to a predefined format
If you are not aware of the format details then your requests/responses might get failed.
I want to get a pdf file content array from one of my sharepoint libraries and encode it to base 64
now it works with this ajax request:
$.ajax({ url: "/sites/pae/_api/web/GetFileByServerRelativeUrl('<url>')/$value?binaryStringResponseBody=true", type: "GET", binaryStringResponseBody: true, success: function(data){ console.log(data) }, error: function(data){console.log(data)} });
but the problem is that it returns a string with unrecognizable characters which makes it impossible to convert to base64
Is there a way to decode it from utf8 or to bring it directly with base64?
I am trying to GET some data from another server into Tally via an XML API. But from the Tally documentation, I can see how to do HTTP POST. But I don't know what is the step by step process to do the HTTP GET using RemoteURL TDL instruction and pass the HTTP Header parameters. Can somebody please help? A sample would be a great help. Thanks!
To fetch data from a remote URL, if you are using POST, you would need to create a report and attach it to the request - this report is actually the POST payload.
POST Request:
[Collection: MakePOSTRequest]
Data Source: HTTP JSON: <insert URL here>
Remote Request: <insert TDL Report Name here> : UTF8
Export Header: <Insert header here>
JSON Object Path: "."
For GET request, you don't need anything except the URL. In case you have query parameters, attach it to the URL directly.
[Collection: MakeGETRequest]
Data Source: HTTP JSON: <insert URL here>
Export Header: <Insert header here>
JSON Object Path: "."
Let's say you have one URL: http://localhost:8000/get_api_data, which accepts both POST and GET requests. Then for the POST request, you would add the parameters via the TDL report, whereas for the GET request, you'd simply add the parameters to the URL this way: http://localhost:8000/get_api_data?key1='xxx'&key2='yyy'.
Not Working for me too..
[Collection: MakeGETRequest]
Data Source: HTTP JSON: 'http://35.198.189.9/api/Send?UserId=11&Guid=123'
JSON Object Path: "."
I would like to do a REST resource that could be represented as:
PDF (binary for download);
JSON (with structured data);
PDF (base64 encode)
My expectation is to create a URL like this:
http://api.mybank.com/accounts/{accountId}/statement?fromDate=2019-11
The Accept header as 'application/json' will return the statement information.
The Accept header as 'application/pdf' will return the statement in a PDF binary file.
And PDF encoded as base64? How I define this?
Content-Transfer-Encoding is not an HTTP, but email header.
Transfer-Encoding is used only for compression.
Is it possible to declare a custom response header which would be present in all responses without copying it in each of the response structure?
This was somewhat improved in OpenAPI 3.0 – you can now can define common headers in the global components/headers section and then $ref these definitions instead of repeating the inline definitions. You can also $ref whole responses (e.g. 400) to reduce the code duplication a bit. However, there's still no way to set common headers for all paths – you'll need to list the headers explicitly in each response.
openapi: 3.0.1
...
paths:
/:
get:
responses:
'200':
description: OK
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
/something:
get:
responses:
'200':
description: OK
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
components:
headers:
X-RateLimit-Limit:
description: Request limit per hour
schema:
type: integer
example: 100
X-RateLimit-Remaining:
schema:
type: integer
example: 96
According to section 2.3 Response’s headers of Writing OpenAPI (Swagger) Specification Tutorial – Part 5 – Advanced Input And Output Modeling the answer is no. Which is what I understand from the 2.0 spec too.
Vote/comment on Structural improvements: enhance headers handling · Issue #690 · OAI/OpenAPI-Specification.