Based on the following https://swagger.io/docs/specification/api-host-and-base-path/ it seems that we can use wss:// and ws:// schemas in OpenAPI documentation.
So, I am just wondering how to represent requests and responses and the source of request because I don't find answers for below points.
There is nothing like GET, POST in websocket right? Should I assume all as POST?
Source of request should be represented, if it is server or client who is making request to who.
Not able to find any examples too for the websocket in Open API format or any other format that I am aware of.
Related
I'm building a web application that needs to process some information on a server. There is no database involved, the server (using Flask) just needs to receive some (complex) information, process it, and send back the result.
My question is which HTTP method is most suitable here (if any). When I read about HTTP methods, they are usually explained in terms of a REST api, where a GET request is used to retrieve data from the server and a POST request is used to create new data on the server. In my case however, I don't need to store any information on the server. A GET request doesn't seem suitable here, as the information sent to the server is rather complex, and can't be easily encoded in the URL. I think a POST request should work here, as I can send the data in JSON format, but the specifications say POST should be used when you want to create something on the server, and a response should only contain a success message and/or location.
Am I missing something here? Should I use something different like WebSocket, or is a POST request fine here, although it doesn't abide by the REST principles?
Thanks in advance.
the specifications say POST should be used when you want to create something on the server
No, they don't. A lot of people say that, but the specification is not so restrictive.
The POST method requests that the target resource process the representation enclosed in the request according to the resource's own specific semantics
Here's how Roy Fielding explained it in 2009:
POST serves many useful purposes in HTTP, including the general purpose of “this action isn’t worth standardizing.”
Yes, POST isn't ideal - the semantics of POST are neither safe nor idempotent, and your particular case would benefit from communicating those properties to general purpose components.
But it is good enough, until the work is done to standardize the semantics of a new method token that better handles this case.
We use POST method to send data to the server. What the server does with the data is encoded in the server logic.
As a client if you want to just send data to server use POST.
What is the most common approach to URI naming for API which uses both HTTP and WebSocket protocols for similar requests? Are there any common conventions for that?
Lets suppose we have a HTTP request returning the collection of users:
localhost/users
This request should return a list of registered users.
On similar WS request, the server should open WebSocket channel and send a list of users to the client over it every time the list is updated (e.g. user was added or removed, etc).
How should the URI for WebSocket request look like?
I see several options:
It may be the same, localhost/users. The difference should be only in the request headers (Upgrade: WebSocket). The drawback is that it can be confusing as requests with same URI return different responses dependent on provided headers
localhost/users-ws. This seems a little bit ugly for me as the API grows each time we have similar WS request for a HTTP request
localhost/users/ws. This breaks the possibility of extending the URI with variable, for example we can't use localhost/users/{id} here no more.
Store all WS requests under common ws domain - localhost/ws/users. This is also ugly as we break the order of domains in the URI and can't redirect requests with users domain to the specific handler
So at the monent I don't see an option without obvious drawbacks:)
If someone can provide any examples of big projects like StackOverflow or GitHub where WS and HTTP are used together, it will be very helpful.
I am not aware of any common naming conventions for WebSockets but for web APIs there is a naming convention to start the route with /api/, example api.example.com/api/users.
Following that practice, it could be argued that example.com/ws/users could be a fitting route name to use.
I am designing a RESTful API. I need to retrieve a resource (complex report) passing a really long list of filters. Something like this:
http://example.com/orders?query=a-very-long-list-of-filters
So I should use GET HTTP verb but if URI exceeds the allowed URL length (by browser, web server or intermediate proxies), can I use POST request with JSON body encapsulating filters to do so? The POST verb is intended for creating resources and updating partially but not for retrieving resources. How can I solve this situation. Please tell me a solution that conforms to REST fundamentals because encoding URL to decrease the length is not an agreeable solution. I have been researching a lot about this but I didn't find a proper and definitive guidelines. Any help will be appreciated.
You can use a POST request as an alternative to GET request to send any large data that might exceed the maximum allowed query string length, but to conform to REST standards, it is recommended that you also send a 'X-HTTP-Method-Override: GET' header while doing so to tell the server to treat it as a GET request. I have seen some some well known libraries such as Google Translate allow this - https://cloud.google.com/translate/v2/using_rest?csw=1#Translate
Is it a good idea to show documentation of a particular REST resource if clients Content-Type is other than application/json? I mean, if a developer tries to fetch a REST resource URL in browser he gets something like this.
Although this is open for discussion but in my opinion that would be a bad idea. The whole purpose of a RESTful API is to expose your application interface for other developers to use. Some developer look at http header to determine if certain route of your REST API existed regardless of the content-type. If I request for a text/plain, I would expected to receive a 404/NotFound if you don't have it and not a documentation with a 200/OK. Although, I suppose it could be useful for manual API testing with browser.
I've never used an API and was wondering how you use them... I would like to use facebook, twitter and vimeo's api,
Can someone explain the basics of using them, how do i access them and use them etc.
Please and thanks
Neil
How to use an API depends on the API. Usually the API creator has documentation on how to use their specific API.
Mostly, things work like the following:
You register to get a developer key. Then, you send requests to the service via HTTP (for example Twitter is using REST, which requires you to send XML or JSON to a specific http-URL providing your key). You get an answer from the service, which you must then parse and react to accordingly (for example filling a list with contacts, etc.).
Most of the time this all comes down to:
Create an XML or JSON document that describes the call parameters
Send the document to an URL using GET, POST or other request methods
Get the server's response
Parse and evaluate the response
The specific ways to use the API, especially performing authentication, can be found on the service's developer pages.
The best way to start if you want to use an API is to read it's documentation, find some tutorials and code examples. This is always/usually published by the one offering an API.
Good luck :)