I'm implementing an API endpoint that serves data but makes no modifications to data - it's something along the lines of "GET all items that match this list of filters", where a filter could be something like "ID > 200" or "propertyA != null".
In actual implementation, I have to send an array to the endpoint, specifying a bunch of resources on a per-id basis to GET back to the client. Something like
GET api/tickets
{
ids: [1, 3, 5, 7, 9],
filter: "on-sale"
}
From what I understand, a Restfully implemented api would not use GET for this kind of request as it's expected that only the id of the target resource is specified in the url, with no contents in the body.
Though I hate to think I would have to hamfist this thing into a PUT or POST request.
What's the right thing to do here?
HTTP does not allow you to sending meaningful information in the GET body. You can however send lists in the request URI.
This URI is perfectly valid.
GET /tickets?ids=1,3,5,7,9&filter=on-sale
Related
I think this is a classic and typical question but I didn't find its answer.
In my knowledge, the POST method is used to send data to the server with request parameter in message body to make it secure. And GET method is to retrieve data with parameters in the URL.
But what I didn't understand is how the same api may have different behavior by just changing the method.
Here is an example. I use SoapUI 5.5.0, this is the link of the api: https://reqres.in/api/users/1
when I use GET method I get this:
{
"data": {
"id": 1,
"email": "george.bluth#reqres.in",
"first_name": "George",
"last_name": "Bluth",
"avatar": "https://s3.amazonaws.com/uifaces/faces/twitter/calebogden/128.jpg"
}
}
and by changing only the method to POST, I get this:
{
"id": "244",
"createdAt": "2020-02-27T14:30:32.100Z"
}
(the id and date changes each time)
as described in this link https://reqres.in/ that it is creating an instance and we can add parameters..
BUT, can any one explain how is it technically possible to have different behavior with different methods on the same URL.
In my knowledge, the POST method is used to send data to the server with request parameter in message body to make it secure. And GET method is to retrieve data with parameters in the URL.
That's probably getting in your way.
HTTP Requests are messages; each message starts with a request-line
method SP request-target SP HTTP-version CRLF
The request-target identifies the target resource upon which to apply the request
The method token indicates the request method to be performed on the target resource.
You can think of it being like a function call
GET(target-resource)
POST(target-resource, message-body)
Or equivalently you can think of the resources as objects that share an understanding of message semantics
target-resource.GET()
target-resource.POST(message-body)
But what I didn't understand is how the same api may have different behavior by just changing the method.
The same way that an api can exhibit different behavior by just changing the request-target.
In HTTP, the request-line is literally human readable text that the server will parse. Having parsed the request-line, the server program can then branch to whatever code it wants to use to do the work, based on the values it found in the message.
In many frameworks (Spring, Rails) the branching logic is provided by the framework code; your bespoke handlers only need to be correctly registered and the framework ensures that each request is forwarded to the correct handler.
how is it technically possible to have different behavior with
different methods on the same URL
for the technical possibility, you can look at the spring framework's answer to this.
You can have a controller that is accessible on a single url but can contacted in four says, GET, PUT, POST, DELETE. To do this, Spring provides the annotations #GetMapping, #PostMapping, #PutMapping, #DeleteMapping.
All the requests are sent to the same url and Spring works out which method to call based on the verb.
In Restful APIs, verbs have very important meaning.
GET: Retrieve data
POST: Create a new entity with the request's body
PUT: Replace an entity with the request's body
PATCH: Update some properties of an entity with the request's body. A.K.A. Partial update
In your case, changing the verb from get to post has the effect of creating a new entity with ID 1. That's why you get a response with the newly created ID and a createdAt timestamp.
I am calling a REST API for a list of resources and getting the json response as below if atleast one resource is there.
{
"value": [
"res1_id",
"res2_id",
"res3_id"
]
}
and the HTTP response code is 200.
But when no resource is there the server is returning HTTP response code as 404.
My doubt it why it is designed that way(it is an enterprise product).
I was expecting a empty list as below and HTTP response code 200:
{
"value": []
}
I am not able to understand what design decision has been taken into consideration to return 404 instead of an empty json.
Please help me to understand the reasoning behind it.
What I am reading here is that you have a 'collection' resource. This collection resource contains a list of sub-resources.
There's two possible interpretations for this case.
The collection resource is 0-length.
The collection resource doesn't exist.
Most API's will treat a 0-length collection as a resource that still exists, with a 200 OK. An empty coffee cup is still a coffee cup. The coffee cup itself did not disappear after the last drop is gone.
There are cases where it might be desirable for a collection resource to 404. For example, if you want to indicate that a collection never existed or never has been created.
One way to think about this is the difference between an empty directory or a directory not existing. Both cases can 'tell' the developer something else.
You're trying to access a resource which does not exist. That's the reason for 404.
As a simple google search says
The HTTP 404, 404 Not Found, and 404 error message is a Hypertext
Transfer Protocol (HTTP) standard response code, in computer network
communications, to indicate that the client was able to communicate
with a given server, but the server could not find what was requested.
For your case
{
"value": []
}
This can be a status code 200 which means the resource is accessed and data is returned which is an empty array or you can customize it to a 404. But for that you've mentioned best is to return 200.
A status code of 404 is the correct response for when there is no resource to return based on a request you made. You asked for data and there is no data. It returns an empty response. They're relying on you to base your interpretation of the results on the status code.
https://en.wikipedia.org/wiki/HTTP_404
Some companies prefer making their errors known instead of hiding them. I know where I work we shy away from try catch blocks because we want our applications to blow up during testing so we can fix the problem. Not hide it. So it's possible that the dev that created the API wants you to use the status code of the response as a way of telling if the service was successful.
I have one question that i am finding hard to clearly identify the correct answer.
My API has one endpoint that does pagination. So, in the response i have to return to the client the total number of lines afected by the query. The count of records in practice.
I have read that, i should be passing metadata like what i want in the body, enveloping it, but i have also read that, it is not ok to afect the body with meta-data and that the future is to return only non meta-data on the body meaning that it must be on the response header.
O'reilly
If the information you are conveying through a custom HTTP header is important for the correct interpretation of the request or response, include that information in the body of the request or response or the URI used for the request. Avoid custom headers for such usages.
So, my question is, what is the correct approach to the problem? Should i pass the number of lines in response headers or put it in the message body.
Thank you very much.
For pagination, you could use an envelope in the response payload:
{
"data": [...],
"paging": {
"first": "http://api.example.com/foo?page=1&size=10",
"previous": "http://api.example.com/foo?page=2&size=10"
"next": "http://api.example.com/foo?page=4&size=10"
"last": "http://api.example.com/foo?page=5&size=10"
}
}
A similar approach is described in the RFC 5005: each page of results is a separate resource, which contains hyperlinks to the previous and next page of results
You also could use the Link header (line breaks are just for readability purposes):
Link: <http://api.example.com/foo?page=1&size=10>; rel="first",
<http://api.example.com/foo?page=2&size=10>; rel="previous",
<http://api.example.com/foo?page=4&size=10>; rel="next",
<http://api.example.com/foo?page=5&size=10>; rel="last"
Check the link relations registered in IANA.
For returning the number of records, I've seen some APIs using custom headers such as X-Total-Count, but I don't recommend such approach. Send those details in the response payload then.
I am a newbie to the apigility code-connected service & was able to create a RESTful service with fetch and fetchall class method on the mapper file.
Can someone point me a good sample for insert (POST) data via REST service ?
Thank you,
Kevin
POST is going to be used for creating a new resource typically. This means that in your request you're going to want the following headers:
Accept: application/json
Content-Type: application/json
The first tells Apigility what sort of a response it is expecting. The second says that the data you'll be providing to the API will be in json format.
Apigility uses json or json+hal by default for a return and expects json for the incoming data.
When you're creating a new resource, typically you'll be persisting it in a database and as such the id of the resource will be generated by your code or database. The rest of the resource will be provided by the caller to the API. Example:
POST /api/user
{
"username": "kevin voyce",
"firstname": "kevin",
"lastname":" "voyce"
}
If you do this, you should see a response of something like
405 - Method Not Allowed
The body of the error should indicate that the method has not been defined. The error message is coming from the create method in the resource. Inside this method, you'll see an argument called $data which at this point will consist of a PHP stdClass with fields matching the stuff you passed in via the JSON body.
This is where the fields part of configuring your API in Apigility comes in. If you set up the names of the fields and put validators on the fields, Apigility will make sure that the fields that are passed in conform to and are valid according to these validators before the call is made into your API. The same applies to not just POST, but PATCH and PUT as well. This means that within your methods you don't have to worry that the input hasn't been validated (as long as you correctly configured your validators).
I want to pass some data within request body, but I'm using GET request, because I just want to modify this data and send it back.
I know that it is bad practice to use body with GET requests.
But what should I do with this situation if I want to build correct RESTful service?
P.S. I'm not changin any object on server.
I'm not putting any new object on server.
You want a POST. Something like
POST /hashes
{
"myInput": ...
}
The response would be the hashed value. There's no rule that the created resource must be retained by the server.
From the RFC:
The action performed by the POST method might not result in a
resource that can be identified by a URI. In this case, either 200
(OK) or 204 (No Content) is the appropriate response status,
depending on whether or not the response includes an entity that
describes the result.