I would have a question concerning the properties which will be transfered from client to server.
HTTP GET is clear: Parameters are transmitted in URL and not in body!
HTTP PUT: where to transmit parameters - in URL or Body?
HTTP POST: where to transmit parameters - in URL or Body?
HTTP DELETE: where to transmit parameters - in URL or Body?
Thanks a ot for answering the question!
The id of the entity in PUT (update) and DELETE request should be in the url. The entity to update in PUT requests should be in the body. The entity to create in POST requests should also be in the body.
Optional parameters should be sent in query string. Other contextual information on the entity (Composite id) should be in the url.
Related
I want to create a new call in my API that links two already created resources together. Therefore, I don't need to pass any json entities in the post body I just need the resources IDs which I am passing in the URL. Is that a wrong practice? so basically my request now is only a simple path {cid}/projects/{projectID}/subcontractors/{subcontractorID}
and in the post call method I extract the resources IDs from the path and I link them. The response is only either pass or fail {"success":true}. Is that a wrong practice? Is there a better way of doing this?
How you will design your API is really up to you. From a technical point of view, a POST request with an empty payload is completely fine.
However, assuming that you intend to add a contractor to a project, I think it could be better expressed with a payload:
POST /projects/1/contractors HTTP/1.1
Host: api.example.org
Content-Type: application/json
{ "contractorId": 100 }
This approach is specially useful if you need to manage more information for that contractor in that project. If above request succeeds, the response would contain the 201 status code along with a Location header that identifies the newly created resource.
Since you are linking the already existing resources - projects and contractors. I wouldn't prefer the POST method.
Instead I would use the PATCH method (as I am only editing the partial content of the existing resources)
Either the payload or the request URL methods are acceptable.
Request URL:
PATCH /projects/3/contractors/23 HTTP/1.1
HOST example.com/api
Payload
PATCH /projects/3/contractors HTTP/1.1
HOST example.com/api
Content-Type: application/json
{ "contractor_id": 23 }
A successful response is indicated by 200 status code which may contain the payload, or
204 response
I am creating Rest API but I am confused in URL structure. I have to send just one parameter to server in my Post request. should I send it through path variable or in request body? what are the best practices?
Example Current URL:
api/v1/users/{id}/name/{name}
name is the variable I want to send to server for to change state
Thanks
URL usually identifies resource you want to update.
So the data should go inside in request body
To update user name you may send this to server:
POST api/v1/users/{id} HTTP/1.1
Content-Type: application/x-www-form-urlencoded
name=string
I have api that is exposed to multiple clients. They all when requesting any resource send me a "sourceId" through which i identify which client the request is coming from:
Should i accept "sourceId" in body or in headers? How would it impact in the future?
Headers make more sense as this is something that would remain static for a particular client but i can't think of a good reason as to how i can decide which parameter to send in body and which in headers?
For some HTTP methods, such as HEAD, GET and DELETE, the request payload has no defined semantics and sending a payload body on a such requests might cause some existing implementations to reject the requests. For further details, check the RFC 7231, the current reference for semantics and content in HTTP/1.1.
Sending the parameter in a HTTP header should work for all HTTP methods though.
If the source identifier is an API key or it's used for authentication, it should be sent in the Authorization header. There are many APIs that define custom HTTP headers like X-API-Key or X-Source-ID. I would avoid that though.
The main reason for it to be in the header is that not all rest methods have a body, for example GET. In most cases the data your request is interested on would be in the body, but information about the request itself would be on the headers.
For example if you want informarion about your sourceid then it would be either in the body or as part of the uri, but if the sourceid is just a way to authenticate the caller when asking for information about something else then it would be in the headers.
If I want to return a status code of 303 See Other when a client POSTs data that already exists, am I allowed to return that data in the content (body) of the response (in addition to setting Location), or must the client then GET the Location?
I would like to avoid requiring the client HTTP to make two HTTP calls if at all possible.
Idiomatically, the client should retrieve the data with a GET request.
I am designing a RESTful API when I noticed something strange.
When I make a POST request for creating a new record, the form data is sent in request payload.
But when I make a PUT request to update a record, it appends form data in the URL, very similar to GET request.
Now a URL has certain length limit. So what would happen if PUT request has larger data than this limit.
Will the PUT request fail?
Is it unsafe to use PUT instead of POST to update a record having large form data?
EDIT:
I am using NodeJS server. I am using restangular(angular framework) to build my PUT request.
Use customPUT to send the form data in payload.
baseObj.customPUT(newObj).then(function(xyz){})
Have a look at these threads
Can HTTP PUT request have application/x-www-form-urlencoded as the Content-Type?
PHP multipart form data PUT request?
application/x-www-form-urlencoded or multipart/form-data?
Sounds like you can basically set a Content-type: multipart/form-data header and be golden. Basically comes down to configuration of the request with restangular and support thereof on the NodeJS server.