Can you use both a path parameter and a query parameter in Swagger 2.0 or 3.0? For example, given the following base URL and path parameter:
/api.example.com/{path}
is it possible to add a query parameter, as in:
/api.example.com/{path}?<query_param>=<query_value>
My use case is the DELETE operation: {path} refers to an object ID to be deleted, and I'd like to add a flag so the requester can specify whether to try and force delete an object that ordinarily would not be deletable (think deleting a non-empty directory in Linux with rm -f). The URLs would then look like:
/api.example.com/{objectID123} (regular delete; will fail if object is non-empty)
/api.example.com/{objectID123}?forceDelete=True (force delete)
I know I can specify both the object ID and the forceDelete flag as query parameters, but that would mean rewriting the DELETE operation as based solely on query parameters, while the other operations are all based on path parameters; I was hoping to keep everything consistent.
I read the documentation, but didn't find this question addressed explicitly. Note that I'm open to another way to handle the DELETE operation if there are best practices I'm not aware of.
Yes, you can have different parameter types in the same operation.
openapi: 3.0.2
...
paths:
/api.example.com/{objectID}:
delete:
parameters:
- in: path
name: objectID
required: true
schema:
type: integer
- in: query
name: forceDelete
schema:
type: boolean
default: false
Our business is looking to create a Swagger document to represent an internal server.
For various reasons, each request is required to include a series of extraneous header parameters:
parameters:
- name: device_id
in: header
required: false
type: string
- name: ip_address
in: header
required: true
type: string
- name: client_id
in: header
required: true
type: string
- name: request_id
in: header
required: true
type: string
The server will reject the request if the parameters are not included but the parameters themselves are unrelated to the request being made.
The primary purpose of the Swagger document is to generate a small number of client applications (all of which we control) to interact with the server.
We could add each parameter explicitly on every request but this would result in repetition within the document and additional handling within the clients. Alternatively, we could regard these parameters as metadata and exclude them from the document, relying on the clients to add them to each request appropriately.
Is there a recommended approach for such parameters?
An OpenAPI definition serves as a contract between the API provider and the clients. It can be used, among other things, to generate client SDKs. So it's expected that an OpenAPI definition describes your API precisely, including the request body format, required parameters, authentication, etc.
All required parameters should be defined explicitly.
To reduce the code duplication, you can define reusable parameters in the global parameters section (for OpenAPI 2.0) or components/parameters section (for OpenAPI 3.0), and then $ref them from individual paths or operations, as shown here:
Swagger/OpenAPI - use $ref to pass a reusable defined parameter
Note that there's currently no way to $ref a group of parameters. The corresponding feature requests are tracked here:
Group multiple parameter definitions for better maintainability
Global/common parameters (this one is closed for some reason, even though it's not implemented)
I created a hyperlink to a file. the file name contains hashtags as a means to separate information.
<div style="height:100%;width:100%">.</div>
translated to...
http://localhost/dir/upload/1427853638#0#file#A101.pdf
Is this a "legal" name in a URL? Im getting a "file not found" error
The requested URL /dir/upload/1427853638 was not found on this server.
So, clearly the # has another meaning in the URL (I understand now, its a location hash property). Is there a way to get this to work, or do i need to use another character besides the # in the file names?
Since # is a special character in the URL semantic (it's used to provide an internal anchor in a HTML page), it should be URL-encoded into %23.
Your URL should be: http://localhost/dir/upload/1427853638%230%23file%23A101.pdf.
NB: you can find an online URL encoder here: http://meyerweb.com/eric/tools/dencoder/
I am receiving HTTP/SOAP request with some query parameters. Those query parameters are in repeated format as key=value as /q=key1=value1&key2=value2 etc...
I would like to retrieve all the keys from above URL and check if they are valid or not.
1. Is there any way to define global array which can hold these keys
2. How to validate if keys are present or not. Does ESB supports java "contains" API ?
I believe you are doing a GET request..
You can retrieve all the query parameters in a sequence.
eg:
For a request url; http:// localhost:8280/getSimpleQuote?symbol=IBM
<property name="symbol" expression="$url:symbol"/> will return the symbol 'IBM'.
After getting all keys, you can validate them
you can get the query parameters with the xpath expression get-property{'uri.var.xxx'} with xxx is the name of the query parameter you need to get.
When a resource is defined with a URL mapping, only those requests that match the given URL mapping will be processed by the resource. Alternatively one could configure a resource with a URI template. A URI template represents a class of URIs using patterns and variables. Some examples of valid URI templates are given below.
/order/{orderId}
/dictionary/{char}/{word}
All the identifiers within curly braces are considered variables. A URL that matches the template “/order/{orderId}” is given below.
/order/A0001
In the above URL instance, the variable orderId has been assigned the value “A0001”. Similarly following URL adheres to the template “/dictionary/{char}/{word}”.
/dictionary/c/cat
In this case the variable “char” has the value “c” and the variable “word” is given the value “cat”. When a resource is associated with a URI template, all requests that match the template will be processed by the resource. At the same time ESB will provide access to the exact values of the template variables through message context properties. For an example assume a resource configured with the URI template “/dictionary/{char}/{word}”. If the request “/dictionary/c/cat” is sent to the ESB, it will be dispatched to the above resource and we will be able to retrieve the exact values of the two variables using the get-property XPath extension of WSO2 ESB:
Is a url like http://example.com/foo?bar valid?
I'm looking for a link to something official that says one way or the other. A simple yes/no answer or anecdotal evidence won't cut it.
Valid to the URI RFC
Likely acceptable to your server-side framework/code
The URI RFC doesn't mandate a format for the query string. Although it is recognized that the query string will often carry name-value pairs, it is not required to (e.g. it will often contain another URI).
3.4. Query
The query component contains non-hierarchical data that, along with
data in the path component (Section 3.3), serves to identify a
resource within the scope of the URI's scheme and naming authority
(if any). ...
... However, as query components
are often used to carry identifying information in the form of
"key=value" pairs and one frequently used value is a reference to
another URI, ...
HTML establishes that a form submitted via HTTP GET should encode the form values as name-value pairs in the form "?key1=value1&key2=value2..." (properly encoded). Parsing of the query string is up to the server-side code (e.g. Java servlet engine).
You don't identify what server-side framework you use, if any, but it is possible that your server-side framework may assume the query string will always be in name-value pairs and it may choke on a query string that is not in that format (e.g. ?bar). If its your own custom code parsing the query string, you simply have to ensure you handle that query string format. If its a framework, you'll need to consult your documentation or simply test it to see how it is handled.
They're perfectly valid. You could consider them to be the equivalent of the big muscled guy standing silently behind the mob messenger. The guy doesn't have a name and doesn't speak, but his mere presence conveys information.
"The "http" scheme is used to locate network resources via the HTTP protocol. This section defines the scheme-specific syntax and semantics for http URLs." http://www.w3.org/Protocols/rfc2616/rfc2616.html
http_URL = "http:" "//" host [ ":" port ] [ abs_path [ "?" query ]]
So yes, anything is valid after a question mark. Your server may interpret differently, but anecdotally, you can see some languages treat that as a boolean value which is true if listed.
Yes, it is valid.
If one simply want to check if the parameter exists or not, this is one way to do so.
URI Spec
The only relevant part of the URI spec is to know everything between the first ? and the first # fits the spec's definition of a query. It can include any characters such as [:/.?]. This means that a query string such as ?bar, or ?ten+green+apples is valid.
Find the RFC 3986 here
HTML Spec
isindex is not meaningfully HTML5.
It's provided deprecated for use as the first element in a form only, and submits without a name.
If the entry's name is "isindex", its type is "text", and this is the first entry in the form data set, then append the value to result and skip the rest of the substeps for this entry, moving on to the next entry, if any, or the next step in the overall algorithm otherwise.
The isindex flag is for legacy use only. Forms in conforming HTML documents will not generate payloads that need to be decoded with this flag set.
The last time isindex was supported was HTML3. It's use in HTML5 is to provide easier backwards compatibility.
Support in libraries
Support in libraries for this format of URI varies however some libraries do provide legacy support to ease use of isindex.
Perl URI.pm (special support)
Some libraries like Perl's URI provide methods of parsing these kind of structures
$uri->query_keywords
$uri->query_keywords( $keywords, ... )
$uri->query_keywords( \#keywords )
Sets and returns query components that use the keywords separated by "+" format.
Node.js url (no special support)
As another far more frequent example, node.js takes the normal route and eases parsing as either
A string
or, an object of keys and values (using parseQueryString)
Most other URI-parsing APIs following something similar to this.
PHP parse_url, follows as similar implementation but only returns the string for the query. Parsing into an object of k=>v requires parse_string()
It is valid: see Wikipedia, RFC 1738 (3.3. HTTP), RFC 3986 (3. Syntax Components).
isindex deprecated magic name from HTML5
This deprecated feature allows a form submission to generate such an URL, providing further evidence that it is valid for HTML. E.g.:
<form action="#isindex" class="border" id="isindex" method="get">
<input type="text" name="isindex" value="bar"/>
<button type="submit">Submit</button>
</form>
generates an URL of type:
?bar
Standard: https://www.w3.org/TR/html5/forms.html#naming-form-controls:-the-name-attribute
isindex is however deprecated as mentioned at: https://stackoverflow.com/a/41689431/895245
As all other answers described, it's perfectly valid for checking, specially for boolean kind stuff
Here is a simple function to get the query string by name:
function getParameterByName(name, url) {
if (!url) {
url = window.location.href;
}
name = name.replace(/[\[\]]/g, "\\$&");
var regex = new RegExp("[?&]" + name + "(=([^&#]*)|&|#|$)"),
results = regex.exec(url);
if (!results) return null;
if (!results[2]) return '';
return decodeURIComponent(results[2].replace(/\+/g, " "));
}
and now you want to check if the query string you are looking for exists or not, you may do a simple thing like:
var exampleQueryString = (getParameterByName('exampleQueryString') != null);
the exampleQueryString will be false if the function can't find the query string, otherwise will be true.
The correct resource to look for this is RFC6570. Please refer to section 3.2.9 where in examples empty parameter is presented as below.
Example Template Expansion
{&x,y,empty} &x=1024&y=768&empty=