Our API returns various response codes. For some response codes 4xx and above, a body may be returned. For example, an HTTP response code of 400 may be returned in several different cases described in the business logic, in some cases the response may contain a body, and in some cases the body may be completely absent.
My question is - how can I describe in the specification a situation where, for the same HTTP response code, for example, for HTTP 400, the API can return a response body or there can be no response body at all?
Addition. I am trying to describe the HTTP response code for the same endpoint.
Examples:
The response contains a body:
'400':
description: Bad Request
content:
application/json:
schema:
$ref: some_ref_here
examples:
example-1:
value:
message:
title: This email address cannot be used
detail: Use a different email address.
severity: error
headers:
Content-Type:
schema:
type: string
description: Some description.
Cache-Control:
schema:
type: string
description: Some description.
Pragma:
schema:
type: string
description: Some description.
The response does not contain a body:
'400':
description: Bad Request
headers:
Content-Type:
schema:
type: string
description: Some description.
Cache-Control:
schema:
type: string
description: Some description.
Pragma:
schema:
type: string
description: Some description.
I'm trying to specify for a 400 HTTP code that it can either contain content, or content can be completely absent.
That's the default. If the responses 'content' field is absent, it won't be validated against the provided response.
On the other hand, if you want to indicate that a response body must be present, you can do that indirectly by checking for a non-empty Content-Length or Content-Type header.
I am currently writing a documentation for an api which returns a json or a pdf (binary) based on the Accept-Header sent to the system.
How can I specify that the response is of type binary or similar?
In the RAML Spec I found the type: file which seems to be what I was looking for. See https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#file
You will need to define the possible responses as below.
responses:
200:
body:
application/octet-stream:
.......
application/json:
........
In addition, you can also specify ACCEPT header with the enum of possible content types.
headers:
Accept:
type: string
enum: [application/octet-stream, application/json]
required: true
I have a swagger.yaml something like this:
swagger: "2.0"
paths:
/something:
get:
parameters:
- name: format
in: query
type: string
pattern: '^(csv|json|xml)$'
responses:
200:
schema:
type: ?
And I want to return different formats (csv, json, xml) depending on the value of the format query parameter (eg. localhost/api/something?format=csv).
How can I specify the different response formats in the spec?
I found a workaround, by providing different endpoints:
swagger: "2.0"
paths:
/something/json:
get:
produces:
- application/json
responses:
200:
schema:
type: object
properties:
...
/something/csv:
get:
produces:
- text/csv
responses:
200:
schema:
type: string
Note the different produces: inside each get, and none at the top level.
The actual response header for the csv endpoint is:
Content-Length:64
Content-Type:text/csv; charset=utf-8
Date:Fri, 26 Aug 2016
I have also tried adding headers to the yaml (straight after the code above), but it doesn't change the actual response header:
headers:
Content-type:
type: string
description: text/csv; charset=utf-8
Content-Disposition:
type: string
description: attachment; filename=data.csv
At either endpoint I get a console message (I am building this using connexion):
Resource interpreted as Document but transferred with MIME type application/json, or
Resource interpreted as Document but transferred with MIME type text/csv
Also, the csv is interpreted as a file to download, not displayed in the browser.
...so I suspect I haven't quite got it right yet.
I'm trying to process the response headers but not sure how to query for them. Here's the code snippet. I commented out a couple of lines when I attempted to read the headers and put some comments on what I noticed.
$http({
method: 'POST',
url: URL,
data: $.param(data),
headers: {'Content-Type': 'application/x-www-form-urlencoded'}
})
.success(function (data,status,headers) {
//Need to process the header to understand the server response
//console.log(headers()); //This returns null
//console.log(headers('custom-myapp-text');// Obvisouls returns null as the headers() returns null
deferred.resolve();
});
return deferred.promise;
};
As per their documentation, the 'headers' returns a function?? Not sure how to query for header values based on this.
data – {string|Object} – The response body transformed with the
transform functions.
status – {number} – HTTP status code of the response.
**headers – {function([headerName])} – Header getter function.**
config – {Object} – The configuration object that was used to generate the request.
statusText – {string} – HTTP status text of the response.
I just tried it with a valid header and it was fine:
console.log(headers('Content-Length'));
This console logged 2 in my example. It will allow you access to any of the valid response headers.
CORS is starting to fry my brain a bit. Everything is good now, apart from one method. I'm building an app with backbone on the frontend and node.js/restify on the backend. The server.coffee looks like this:
server.get '/todos', todos.find_all
server.get '/todos/:id', todos.find_by_id
server.del '/todos/:id', todos.delete
Whenever a model in backbone calls destroy however I get this rather annoying error:
MLHttpRequest cannot load http://localhost:8080/todos/. Method DELETE is not allowed by Access-Control-Allow-Methods.
I read about this a bit and using restify done the following:
unknownMethodHandler = (request, response) ->
if(request.method.toLowerCase() == 'options')
allowHeaders = ['Accept', 'Accept-Version', 'Content-Type', 'Api-Version']
if(response.methods.indexOf('OPTIONS') == -1) then response.methods.push('OPTIONS')
response.header 'Access-Control-Allow-Credentials', true
response.header 'Access-Control-Allow-Headers', allowHeaders.join(', ')
response.header 'Access-Control-Allow-Methods', ['GET', 'DELETE', 'TEST!']
response.header 'Access-Control-Allow-Origin', request.headers.origin
response.send 204
else
response.send new restify.MethodNotAllowedError()
server.on 'MethodNotAllowed', unknownMethodHandler
But even still, I get this as the response header:
HTTP/1.1 204 No Content
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, X-Api-Version
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Api-Version, X-Request-Id, X-Response-Time
Connection: Keep-Alive
Date: Mon, 04 Feb 2013 12:24:25 GMT
Server: restify
X-Request-Id: fbd4e15a-a22e-48b6-bf5c-a46b94926748
X-Response-Time: 0
I just don't get what I'm doing wrong!
If you're expecting a response, you should use a '200' response code, not a 204 as that's a No Content response. See the W3C Spec for the details
9.7 DELETE
The DELETE method requests that the origin server delete the resource identified by the Request-URI. This method MAY be overridden
by human intervention (or other means) on the origin server. The
client cannot be guaranteed that the operation has been carried out,
even if the status code returned from the origin server indicates that
the action has been completed successfully. However, the server SHOULD
NOT indicate success unless, at the time the response is given, it
intends to delete the resource or move it to an inaccessible location.
A successful response SHOULD be 200 (OK) if the response includes an entity describing the status, 202 (Accepted) if the action has not
yet been enacted, or 204 (No Content) if the action has been enacted
but the response does not include an entity.
If the request passes through a cache and the Request-URI identifies one or more currently cached entities, those entries SHOULD
be treated as stale. Responses to this method are not cacheable.
You're seeing the Access-Control-Allow-Origin: * in the response header. This is coming from the .../restify/lib/router.js preflight() method. The comment states "user will need to defined their own .opts handler".
Use server.opts method to wirte your own handler for OPTIONS request.
Below is the example you can use.
Also tell me if you are using set-credentials flag to true while making request from the browser. This handle in that case would have to respond with access cookies.
In the example below, I am returning the allowed origin for exact match.
You can tweak it to be substring match also. But always return the exact value as found in request header origin in the response header 'Access-Control-Allow-Origin'. Its a good practice.
server.opts('/api/(.)*', (req, res) => {
const origin = req.header('origin');
const allowedOrigins = ['example.com', 'example.org'];
if (allowedOrigins.indexOf(origin) === -1) {
//origin is not allowed
return res.send(405);
}
//set access control headers to allow the preflight/options request
res.setHeader('Access-Control-Allow-Origin', header);
res.setHeader('Access-Control-Allow-Headers', 'Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, X-Api-Version');
res.setHeader('Access-Control-Allow-Methods', 'GET,POST,PUT,PATCH,DELETE,OPTIONS');
// Access-Control-Max-Age header catches the preflight request in the browser for the desired
// time. 864000 is ten days in number of seconds. Also during development you may want to keep
// this number too low e.g. 1.
res.setHeader('Access-Control-Max-Age', 864000);
return res.send(200);
});
Just set header res.setHeader('Access-Control-Allow-Methods', '*');
Here is the answer: https://github.com/mcavage/node-restify/issues/296#issuecomment-12333568