Problem Statement
A client Foo sends HTTP requests to an API Bar.
Bar provides a special endpoint Baz for Foo to call whenever Bar tells it to. Baz is an endpoint to refresh the user's claims. By design, these are very special claims not meant to be transported in a JSON Web Token.
Proposed Solution
A possible solution is to have a custom response header X-Baz with a boolean value. Foo checks every HTTP response for X-Baz: true to call Baz right after.
Question
Does that approach have any disadvantages apart from its synchronous nature? I'm aware of custom request headers to have difficulties to pass certain reverse-proxy settings. Is there a similar problem with proxies filtering or blocking responses with custom headers?
Notes
Even though it is not recommended anymore to use the X- prefix for custom headers, I used it here to emphasise the custom nature of this header.
A real-time feedback, such as with SignalR, is definitely a good solution. It enables Bar to immediately tell Foo to call Baz. This type of technology is already under consideration, I'm merely looking for simpler solutions.
Related
Let's imagine I have an application where users can either completely, or partially, update their profile details in one part of the app.
PUT for all requests
a PUT (for complete updates) and PATCH (for partial updates) for the requests
In the second scenario I could let the frontend decide whether the full or just a part of the profile was updated. However, this would involve both more code on both the front- and backend.
The first method is on the other hand "easier" to implement. However, is it against certain REST specs / principles?
is it against certain REST specs / principles?
It depends on how you mean it.
If you are thinking "all profile changes are performed by sending a complete replacement of the profile resource via an HTTP PUT", then yes, that is aligned with REST principles (specifically, it respects the uniform interface constraint -- you are using the HTTP PUT message the same way it is used everywhere else, which means that general purpose clients can interface with your resources).
On the other hand, if, instead of the complete replacement, you are considering sending a partial replacement via HTTP PUT, then that is not consistent with REST principles (because you are deviating from the standardized semantics of HTTP PUT).
If HTTP had a standardized "partial PUT" method, using this hypothetical method would be consistent with REST principles.
In other words, REST doesn't really say anything about what messages should be included in the "uniform interface". It just says that everybody should use those messages the same way. It's the HTTP standard that says PUT means complete replacement.
I am writing a service where the client makes an API call to my service, and my service then augments the request payload, then passes it on to another service. For my API, what should the HTTP method be if it's not interacting with a database?
what should the HTTP method be
Key idea: the fact that your server communicates with another API, rather than a database, or a filesystem, is an implementation detail; details of your implementation are not supposed to be leaking into your messages.
Given that the incoming request has a message body; GET, HEAD, DELETE are all right out, because those methods have no defined semantics for a payload.
POST/PUT/PATCH are all possible.
Ideally, you would match the method token that you are using to talk to your back end. This is essentially how a reverse proxy works. You're just playing man in the middle, after all, so it shouldn't be too much of a surprise that the request semantics match.
They don't always, of course - and you might want to inject your own semantics if you find that the API you are calling has made poor method choices in its own design.
When in doubt, it is okay to use POST
One of the REST principles — namely, ‘Layered System’ constraint — implies that:
each component cannot "see" beyond the immediate layer with which they are interacting
So you actually should not make any difference between ‘simple’ and ‘proxied’ API calls.
When to use RestRequest/RestResponse and when to use HttpResuest/HttpResponse?
I am learning REST in Saleforce. I know there are methods like GET, POST, PUT, PATCH, DELETE.
But having confusion in these both and can I use Http request/Http Response instead of RestRequest/Restresponse ?
RestRequest/RestResponse are custom functions that allow you to listen for outside REST API requests from Apex code. You define a #RestResource annotated class and it functions much like the built in SF Rest API (although with the logic that you define). The different HTTP methods you mention are meant to respond (at a specific path) to different types of outside requests. A REST GET method should get a record. SF already has a REST API that follows these rules. They just enable you to write the logic to get the record (in this example) yourself, should you have some custom logic you wish to implement. Here is a link to the MDN docs that describe the different HTTP methods.
An HTTP request/response is when you wish to, from inside your APEX code, make a callout to some resource outside of SF.
In other words, think of RestRequest/RestResponse as a server method and HTTP as a client method.
I have an API that will delete a resource (DELETE /resources/{resourceId})
THE above API can only tell us to delete the resource. Now I want to extend the API for other use cases like taking a backup of that resource before deleting or delete other dependant resources of this resource etc.
I want to extend the delete API to this (DELETE /resources/{resourceId}?backupBeforeDelete=true...)
Is the above-mentioned extension API good/recommended?
According to the HTTP Specification, any HTTP message can bear an optional body and/or header part, which means, that you can control in your back-end - what to do (e.g. see what your server receives and conventionally perform your operation), in case of any HTTP Method; however, if you're talking about RESTful API design, DELETE, or any other operation should refer to REST API endpoint resource, which is mapped to controller's DELETE method, and server should then perform the operation, based on the logic in your method.
DELETE /resources/{resourceId} HTTP/1.1
should be OK.
Is the above-mentioned extension API good/recommended?
Probably not.
HTTP is (among other things) an agreement about message semantics: a uniform agreement about what the messages mean.
The basic goal is that, since everybody has the same understanding about what messages mean, we can use a lot of general purpose components (browsers, reverse proxies, etc).
When we start trying to finesse the messages in non standard ways, we lose the benefits of the common interface.
As far as DELETE is concerned, your use case runs into a problem, which is that HTTP does not define a parameterized DELETE.
The usual place to put parameters in an HTTP message is within the message body. Unfortunately...
A payload within a DELETE request message has no defined semantics; sending a payload body on a DELETE request might cause some existing implementations to reject the request
In other words, you can't count on general purpose components doing the right thing here, because the request body is out of bounds.
On the other hand
DELETE /resources/{resourceId}?backupBeforeDelete=true
This has the problem that general purpose components will not recognize that /resources/{resourceId}?backupBeforeDelete=true is the same resource as /resources/{resourceId}. The identifiers for the two are different, and messages sent to one are not understood to affect the other.
The right answer, for your use case, is to change your method token; the correct standard method for what you are trying to do here is POST
POST serves many useful purposes in HTTP, including the general purpose of “this action isn’t worth standardizing.” -- Fielding, 2009
You should use the "real" URI for the resource (the same one that is used in a GET request), and stick any parameters that you need into the payload.
POST /resources/{resourceId}
backupBeforeDelete=true
Assuming you are using POST for other "not worth standardizing" actions, there will need to be enough context in the request that the server can distinguish the different use cases. On the web, we would normally collect the parameters via an HTML form, the usual answer is to include a request token in the body
POST /resources/{resourceId}
action=delete&backupBeforeDelete=true
On the other hand, if you think you are working on an action that is worth standardizing, then the right thing to do is set to defining a new method token with the semantics that you want, and pushing for adoption
MAGIC_NEW_DELETE /resources/{resourceId}
backupBeforeDelete=true
This is, after all, where PATCH comes from; Dusseault et al recognized that patch semantics could be useful for all resources, created a document that described the semantics that they wanted, and shepherded that document through the standardization process.
Just started my first WCF rest project and would like some help on what are the best practices for using REST.
I have seen a number of tutorials and there seems to be a number of ways to do things...for example if doing a POST, I have seen some tutorials which are setting HttpStatusCodes (OK/Errors etc), and other tutorials where they are just returning strings which contain result of the operation.
At the end of the day, there are 4 operations and surely there must be a guide that says if you are doing a GET, do it this way, etc and with a POST, do this...
Any help would be appreciated.
JD
UPDDATE
Use ASP.NET Web API.
OK I left the comment REST best practices: dont use WCF REST. Just avoid it like a plague and I feel like I have to explain it.
One of the fundamental flaws of the WCF is that it is concerned only with the Payload. For example Foo and Bar are the payloads here.
[OperationContract]
public Foo Do(Bar bar)
{
...
}
This is one of the tenants of WCF so that no matter what the transport is, we get the payload over to you.
But what it ignore is the context/envelope of the call which in many cases transport specific - so a lot of the context get's lost. In fact, HTTP's power lies in its context not payload and back in the earlier versions of WCF, there was no way to get the client's IP Address in netTcpBinding and WCF team were adamant that they cannot provide it. I cannot find the page now but remember reading the comments and the MS guys just said this is not supported.
Using WCF REST, you lose the flexibility of HTTP in expressing yourself clearly (and they had to budge it later) in terms of:
HTTP Status code
HTTP media types
ETag, ...
The new Web API, Glenn Block is working addresses this issue by encapsulating the payload in the context:
public HttpResponse<Foo> Do(HttpRequest<Bar> bar) // PSEUDOCODE
{
...
}
But to my test this is not perfect and I personally prefer to use frameworks such as Nancy or even plain ASP NET MVC to expose web API.
There are some basic rules when using the different HTTP verbs that come from the HTTP specification
GET: This is a pure read operation. Invocation must not cause state change in the service. The response to a GET may be delivered from cache (local, proxy, etc) depending on caching headers
DELETE: Used to delete a resource
There is sometimes some confusion around PUT and POST - which should be used when? To answer that you have to consider idempotency - whether the operation can be repeated without affecting service state - so for example setting a customer's name to a value can be repeated multiple times without further state change; however, if I am incrementing a customer's bank balance this cannot be safely be repeated without further state change on the service. The first is said to be idempotent the second is not
PUT: Non-delete state changes that are idempotent
POST: Non-delete state changes that are not idempotent
REST embraces HTTP - therefore failures should be communicated using HTTP status codes. 200 for success, 201 for creation and the service should return a URI for the new resource using the HTTP location header, 4xx are failures due to the nature of the client request (so can be fixed by the client changing what they are doing), 5xx are server errors that can only be resolved server side
There's something missing here that needs to be said.
WCF Rest may not be able to provide all functionality of REST protocol, but it is able to facilitate REST protocol for existing WCF services. So if you decide to provide some sort of REST support on top of the current SOAP/Named pipe protocol, it's the way to go if the ROI is low.
Hand rolling full blown REST protocol maybe ideal, but not always economical. In 90% of my projects, REST api is an afterthought. Wcf comes in quite handy in that regard.