is there a way to limit swagger query params? for example - if somebody submits a GET request like:
/users/bob?product=10
and accidentally typed in /users/bob?products=10 - is there a swagger property I can add that will then throw an error?
Swagger allows you to describe the REST APIs. If product is the only query parameter allow, then the server should throw an exception if it finds other query parameters in the request from the client.
In other words, there's no way in Swagger to say parameters with certain names are not allowed as other parameters not documented in Swagger are disallowed by default.
I was working on Swagger generated OpenAPI specification and I noticed that if we pass some extra fields in PUT/POST API endpoint, then the server doesn't throw any error, even though it process all valid/necessary field.
So my doubt is that
Should the server throw error in this case?
Is it the OpenAPI standard to allow unknown fields and then ignore them?
In Swagger specification 2.0 there is no option to reject the extra fields passed in the request body. Server will only accept those fields that are allowed in the request definition and other fields will be ignored.
If you want to disallow extra fields then you can handle these in the backend manually.
Whenever searching for this I find resources on how to specify the media type of a resource that the schema defines, but I can't see an answer on what the actual media type of the schema itself is.
Given the way HTTP works, it makes sense to me that if I request the right content type with the Accept header, my server can respond appropriately.
Thus, if I request /products with Accept: application/json I would get products in JSON format, but if I requested openapi-whatever I would get the OpenAPI schema.
I think I can probably use either application/openapi+json or application/openapi+yaml, but I can't see anything about it in the actual specification.
I'm not sure whether or not I actually want to use the Accept header for this difference, but I certainly want to respond with the correct Content-Type header in any case.
The OpenAPI Initiative's Technical Steering Committee (TSC) approved the following media types:
application/vnd.oai.openapi (YAML variant)
application/vnd.oai.openapi+json (JSON only variant)
with an optional version parameter:
application/vnd.oai.openapi;version=2.0
However, these media types are not yet registered with IANA.
This seems to be newer (Sept. 2021):
application/openapi+yaml
application/openapi+json
https://www.ietf.org/archive/id/draft-polli-rest-api-mediatypes-00.html
first of all I'd like to thank the team for this amazing project, it is indeed exiting to be able to start writing server-side software in Swift.
I'm successfully running a POC using PerfectServer on an Ubuntu VM and working on the API to interact with the mobile client.
There is one aspect I didn't quite understand yet, and that is accessing the request body data from my PerfectServer Handler.
Here is the workflow I have in mind:
The client submits a POST request to PerfectServer including some
JSON encoded body data
Once that hits the "valuesForResponse:" of
my server side Handler, I retrieve the WebRequest representation of
my request successfully
The request object does expose a many
properties of the HTTP request, including headers and the url-like
formatted query parameters.
Unfortunately, I cannot see a way to retrieve the underlying request body data. I would expect that to be some kind of public properties exposing the raw data that my handle can retrieve and decode in order to process the request.
The only example provided in the Examples workspace that comes with the project and sends a POST request that includes a body is in the project Authenticator. Here the HTTP body part takes the form os a UTF-8 encoded string where the values are query-params-like formatted.
name=Matteo&password=mypassword
This gets somehow exposed on the server handler by the WebRequest "param" property, that in the inner implementation of HTTPServer seems to expect an "&" separated string of key-values:
What I would expect is to have a way to provide body data in whatever form / encoding needed, in my case a JSON form:
{"name":"Matteo", "password":"psw"}
and be able to access that data from the WebRequest in my handler, decode it and use it to serve the request.
To summarise, I assume you could say that a WebRequest.bodyData public property is what I am after here :).
Is there something I am missing here?
Thanks in advance for any clarification!
Shouldn't PUT be used to Create and POST used to Update since PUT is idempotent.
That way multiple PUTs for the same Order will place only one Order?
The difference is that a PUT is for a known resource, and therefor used for updating, as stated here in rfc2616.
The fundamental difference between the POST and PUT requests is
reflected in the different meaning of the Request-URI. The URI in a
POST request identifies the resource that will handle the enclosed
entity. That resource might be a data-accepting process, a gateway to
some other protocol, or a separate entity that accepts annotations. In
contrast, the URI in a PUT request identifies the entity enclosed with
the request -- the user agent knows what URI is intended and the
server MUST NOT attempt to apply the request to some other resource.
I do see where you are coming from based on the names themselves however.
I usually look at POST as it should be the URI that will handle the content of my request (in most cases the params as form values) and thus creating a new resource, and PUT as the URI which is the subject of my request (/users/1234), a resource which already exists.
I believe the nomenclature goes back a long ways, consider the early web. One might want to POST their message to a message board, and then PUT additional content into their message at a later date.
There's no strict correspondence between HTTP methods and CRUD. This is a convention adopted by some frameworks, but it has nothing to do with REST constraints.
A PUT request asks the server to replace whatever is at the given URI with the enclosed representation, completely ignoring the current contents. A good analogy is the mv command in a shell. It creates the new file at the destination if it doesn't exist, or replaces whatever exists. In either case, it completely ignores whatever is in there. You can use this to create, but also to update something, as long as you're sending a complete representation.
POST asks the target resource to process the payload according to predefined rules, so it's the method to use for any operation that isn't already standardized by the HTTP protocol. This means a POST can do anything you want, as long as you're not duplicating functionality from other method -- for instance, using POST for retrieval when you should be using GET -- and you document it properly.
So, you can use both for create and update, depending on the exact circumstances, but with PUT you must have consistent semantics for everything in your API and you can't make partial updates, and with POST you can do anything you want, as long as you document how exactly it works.
PUT should be used for creates if and only if possible URI of the new resource is known for a client. New URI maybe advertised by the service in resource representation. For example service may provide with some kind of submit form and specify action URI on it which can be a pre populated URI of the new resource. In this case yes, if initial PUT request successfully creates resource following PUT request will only replace it.
It's ok to use POST for updates, it was never said that POST is for "create" operations only.
You are trying to correlate CRUD to HTTP, and that doesn't work. The philosophy of HTTP is different, and does not natively correspond to CRUD. The confusion arises because of REST; which does correspond to CRUD. REST uses HTTP, but with additional constraints upon what is allowed. I've prepared this Q & A to explain the HTTP approach to things:
What's being requested?
A POST requests an action upon a collection.
A PUT requests the placement of a resource into a collection.
What kind of object is named in the URI?
The URI of a POST identifies a collection.
The URI of a PUT identifies a resource (within a collection).
How is the object specified in the URI, for POST and PUT respectively?
/collectionId
/collectionId/resourceId
How much freedom does the HTTP protocol grant the collection?
With a POST, the collection is in control.
With a PUT, the requestor is in control (unless request fails).
What guarantees does the HTTP protocol make?
With a POST, the HTTP protocol does not define what is supposed to happen with the collection; the rfc states that the server should "process ... the request according to the [collection's] own specific semantics." (FYI: The rfc uses the confusing phrase "target resource" to mean "collection".) It is up to the server to decide upon a contract that defines what a POST will do.
With a PUT, the HTTP protocol requires that a response of "success" must guarantee that the collection now contains a resource with the ID and content specified by the request.
Can the operation result in the creation of a new resource within the collection?
Yes, or no, depending upon the contract. If the contract is a REST protocol, then insertion is required. When a POST creates a new resource, the response will be 201.
Yes, but that means the requestor is specifying the new ID. This is fine for bulletin boards, but problematic with databases. (Hence, for database applications, PUT will generally not insert, but only update.) When a PUT creates a new resource, the response will be 201.
Is the operation idempotent?
A POST is generally not idempotent. (The server can offer any contract it wishes, but idempotency is generally not part of that contract).
A PUT is required to be idempotent. (The state of the identified resource is idempotent. Side effects outside of that resource are allowed.)
Here is the rfc:
https://www.rfc-editor.org/rfc/rfc7231#section-4.3.3
It depends..
you can create/update sites/records with both.
When the client is specifying the URI then PUT is the way to go.
e.g. Any Code Editor like Dreamweaver, PUT is the right protocol to use.
have also a look at this thread: put vs post in rest