Hot answers tagged

149

For any error message (and mostly for any message at all), you need to ask yourself: Who is the audience of the message? What can they do about the problem? What information do they need to solve the problem? I would argue that knowing the regex is pretty much useless to the end user, because even if they know what a regex is, it doesn't help them fix the ...


73

For long-running operations, it often helps to model the active job as a REST resource with its own structure and/or sub-resources. For example, starting a job may return a result such as 202 Accepted Location: https://example.com/jobs/123 At that URL, the client will get a structure such as { "status":"running" } as long as the job ...


31

Yes, this is bad for various reasons. A normal end user is not going to gain anything from reading the validation regex over just reading an error message. An attacker may or may not be able to use the exact regex to craft an attack string that causes denial of service or compromise of security. This is not likely, but it's certainly more likely with the ...


16

As someone who previously used email addresses that too many sites thought were invalid, I appreciated at least knowing that you used a regex for validation, because unless all it does is check for an @ with at least one character on each side, I almost guarantee you got it wrong. In the worst case I saw, it accepted my email during registration, but later ...


13

Is there a RESTful way to implement this whilst maintaining atomicity of the operation? Short Answer Just use POST Medium Answer Seriously; it is okay to use POST. POST serves many useful purposes in HTTP, including the general purpose of “this action isn’t worth standardizing.” -- Fielding, 2009 Long Answer REST doesn't have collections. REST has ...


10

Best practice is to avoid temporal coupling in REST. (Temporal coupling is requirements than operations should be performed in a specified order.) Alternatively you could have a POST to A return the URL for B. Then there is no way to request B before A. Your talk of "calling endpoint" indicates you think of this API more like a RPC service rather ...


10

From a general security perspective, the "best practice" principle is to avoid exposing internal details of the system to a user when an error occurs, to prevent a hacker from using that information to breach the system. That's why IIS operates in two modes: a "User Mode," where a faulty page displays, at most, an HTTP response code like ...


8

The client should display an error message when no document meets the filter, and ask for confirmation when there are many documents because it might take a while to process them (let's say the confirmation should trigger at 10 documents). Both cases are 200 OK. OK, Foos resource exists, but I didn't find the subset you are looking for OK, Foos resource ...


7

For endpoints denoting a single resource, such as /products/{productId} it's best to return this resource, not a list. If it does not exist, a 404 error is appropriate. If you'd access the resource using a query parameter /products?id={productId} you've got a different situation. In this case a one-element or empty list would be the right result. (Edit:) As @...


7

CLI programs often resort to file or stdin based input when data is more complex than can be properly communicated via command line. For example, GNU grep allows multiple patterns on the command line, but also supports passing patterns in a file. If your data is nested as in your example, writing it down within the limitations of the command line is error-...


7

REST and GraphQL do not play on the same field. What to pick depends of course on your use-case. If you want to have a database-like access, you probably will lean in the direction of GraphQL. GraphQL is roughly like SQL, it is a language to get data. If you want independent, scalable components with loose coupling you'll probably lean in the direction of ...


7

The problem here is that Tim Bray doesn't explain why he thinks it's not idempotent. The concept of idempotency is somewhat subjective. When we call a PUT twice there are a number of things that aren't the same as when we call it once. For example, the server access logs will be different as well as other logging. There might be other side effects to the ...


6

It's easier to handle when you have different APIs for different matters. Authentication POST /auth or POST /login doesn't matter. Use the one you like most for authentication. As for the response, the token you mentioned is OK. GET /users with parameters email and password. The endpoint would return name, email, access_token. Since we are speaking about ...


6

As an API consumer I would think that adding ?limit=10 would return the first 10 matching results, not throw an error if there are more than 10 results. You could consider changing from the limit to an Expect HTTP request header. Then if there are more results then expected, return a 417


6

One possible solution might indeed be to drop that "should not (imho) imply a DELETE". While it is somewhat counterintuitive that a constructive REST verb (POST) could have a destructive side effect, in general it is relatively normal to have side effects beyond the creation of a new resource (for example, POST on a comments endpoint might have a ...


6

is it ok if I return 400 bad request 4xx does not look like a proper status code if the goal is only to prevent calling a method before another one. Specifically, 400 indicates that the server was unable to process the request sent by the client due to invalid syntax (or size too large, invalid request message framing, or deceptive request routing etc), ...


6

All user data sent to you end up in bytes. Even the strings. Taking the data as not-strings rather than as strings only means you’re taking them as something else. So long as you understand that something else as well as you understand strings there’s no problem with bytes. However, user data shouldn’t be trusted. It should be validated to ensure it only has ...


6

How many other clients to this API will there be? If this is the only client, why not. Its use case is tailored to just this usage, just this representation. Assuming your client isn't trying to be smart and load/cache the object across end points, this can be a very efficient way of writing an API. When your client changes its easy to cleanup old code paths ...


6

The idea that App 2 makes a request back to App 1 is a common architecture to get web services to work together. Usually, this would work like this: App 1 makes a request to App 2 the request contains an URL on App 1 to be called upon completion App 2 responds to the requests, and begins background work eventually, App 2 requests the URL provided by App 1'...


5

REST doesn't care what spelling conventions you use for your URI. An identifier like /ac8a98b3-553a-4eb3-9878-e143f3f52a4e is fine. REST doesn't particularly care about clashes with "fetch by id". You are allowed to write request handlers that branch. See, for example, the rails routing conventions, which specifically use hints that sit in the ...


5

To add to what Ewan has said, since HTTP already has "stringly" typed parameters, so it can be impossible to parse the parameters correctly. You should aim for precision in being able to express your intent. You will already have a lot of other factors to deal with, but you don't want to have design ambiguity as part of it. Ewan gives the counter-...


5

I would not have the applied state associated with a coupon. You need to check the coupons validity at two points. When the customer 'applies' it to their basket. This stops the customer adding used/invalid tokens When the customer purchases the basket. This stops the token being used twice After the coupon has been actually used, it is invalidated. So, ...


5

You mix a couple of things here, let's go in order: 1. "Event sourcing" is not a competing thing to "REST Endpoints", they have absolutely nothing to do with each other. "Event sourcing" is just a storage strategy for things that are best represented as a series of changes, instead of the end-state. "REST API" (I think ...


5

In my opinion, there's a design flaw if your system requires you to call a REST API in specific steps. As other user posted, you should avoid temporal coupling in REST. If A and B run processes, and calling B runs a process that sets the state of the system up before you can call A, that isn't REST! REST Is largely about HTTP methods on resources. The state ...


4

To allow a variety of queries on such data, which transfer only the requested amount of bits and bytes over the network, one needs to preprocess and optimize the data for this purpose, there is no way around this. That is exactly what databases are made for. Trying to make things simpler by "avoiding a database" will end up in building a database ...


4

The identifier in the URL can be always faked by an attacker. You need a mechanism to ensure that the identifier is actually valid. This is why when modelling endpoints executing a certain operation, the url value is not considered a granting authority and instead a different mechanism is implemented (sessions, JWT tokens,...). And then if you decide you don'...


4

You wouldn't return an empty list or null in a RESTful API -- you'd return a 404, which doesn't need a response body. In a query or search (which /products is), I would expect to get a enumerable of some sort back. In a fetch (/products/{id}), I'd expect just the object itself.


4

You could manage it in code by creating v1 and v2 packages with the functionality that differs and having some code to decide which version to run from the controller level. It is entirely possible, but it will be hard to keep track of even with a high level of discipline. What you might consider doing is maintaining long running branches for v1 and v2 in ...


4

The reason that diagram 2 calls this the "presentation layer" is because that's the conceptual "layer" in which REST is presented in ASP.NET MVC It's essentially an "end-point." The reason that diagram 1 calls this the "Service Layer" is because that's where SOAP and REST are represented in that diagram. The "...


4

They should communicate over a communication channel. Of which there are many out there: Web Requests UDP Pipes Semaphores Files ... Sharing is tricky, micro-services are about ownership. Straight up a service Owns its own code, and its own data. The only thing it shares is the communication channels, and even then it owns its end of the channel. This ...


Only top voted, non community-wiki answers of a minimum length are eligible