Simple question. I read a bunch of articles about API design and didn't find the answer.
How should API's endpoints interact with each other?
For example, if I have 2 endpoints: /category/:name and /messages. What is the best way for example to check category existence from messages?
1) Database query from /messages handler like: SELECT * FROM categories WHERE name = 'test'?
or
2) HTTP request from /messages handler to that endpoint like: httpclient.get('/category/test') ?
or
3) Client should get all categories, get ID of particular category and send request to /messages with that category ID?
The question is simple but not an answer. One thing is sure, never use (2) solution. Requesting some data using http client when you can invoke a method will decrease performance and capacity of your API.
If checking existence of a particular category is required to create response in /messages then use (1) but instead of invoking SQL query invoke the same method as used to handle request to /category/test just invoke it locally not through HTTP.
Solution (3) is the REST-way when each endpoint is responsible only for one type of resources. The disadvantage is that it may require more HTTP requests from client to API.
You should design your application in a way that all the endpoint are calling internal APIs for performing the task. When you want to invoke one operation inside other then you should use the respective internal API instead of any other approach like calling http service.
Related
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 am creating a Web Api integrates with SignalR.
I want to create a Web Api method that will receive a string/object as parameter (from an winform exe) and broadcast it to all the SignalR clients.
I know that Web Api uses HTTP requests like PUT DELETE POST GET. All of these requests are database related, i.e. PUT for Update, DELETE for Delete, POST for Insert, GET for Select.
In this case, which HTTP request should I use?
public void BroadcastToClients() {}
Or should I consider WCF instead of Web Api?
People tend to get all up-tight about "pure" REST vs just getting something to work. For every cited reference that argues for one scheme, you can find another that is the opposite.
My very personal opinion is that POST is when something new is to be created, and PUT when an entity is to be updated.
I think the important thing is to just be consistent.
in developing your own RESTful API. does it necessarilly needed to use the four different http methods? GET POST PUT & DELETE?
i was checking the Twitter REST API and saw that they are just using the common methods (GET & POST)
Short answer: No
Long Answer:
REST is not specific to any one protocol, instead it is a style of programming. This is helpful to keep in mind because a RESTful endpoint should be thought of as having specific goals. Your job is to expose the web service in the most RESTful way possible.
When you're making a RESTful API you are not required to use any specific HTTP methods. Instead, REST can be embodied in this guiding principal: That you must expose individually identifiable resources; these resources must be manipulable in their exposed form. Oh and use self descriptive messages.
I'm sure this is a leaky explanation. Try to see, though, that REST becomes much more clear when you have the key idea in mind. RESTful practices expose resources in a way that allows us work with state in a sane manner. The technical details of how to implement a RESTful API can be learned by reading this:
http://en.wikipedia.org/wiki/Representational_state_transfer
After that, read something specific to your language. Fast track: find some RESTful API written in your language and clone it/play with it.
You should use whatever HTTP methods are appropriate for the operations you expose.
For example, you should accept HTTP DELETE requests only for operations that delete things.
If your API does not allow callers to delete things (eg, a traffic or weather API), you should not accept the DELETE verb.
Only if you are going to support those logical operations:
GET - fetch a resource
PUT - update (or create) a resource
DELETE - delete a resource
POST - several uses: create a new resource in a collection, perform some operation that will alter a resource in some one (as opposed to PUTting an entirely new version of a resource)
Most APIs will want to to provide those operations, and will use all those methods. And don't forget HEAD - fetch information about a resource (but not the resource itself).
I'm developing a WCF SOAP web service based on this schema.
Basically it takes product orders from many clients.
As part of the submit operation the client is allowed to provide a URL where it expects asynchronous status updates on the order and it's line items.
I want to know if anyone has experience with a similar architecture? How did you go about implementing this?
Can i use a dynamic web reference as stated here? I would think this won't work very well in this situation. I'm pretty sure i'll need Chuck Norris to handle all the exceptions that get throw at the presence of any client service that is not identical or slightly different... even if it does pass schema validation.
The best thing i can think of is building the status object, serializing it into the SubmitResponse request soap message xml then sending it off using curl. something like:
curl -d "<my soap message xml>" "http://www.example.com/target"
Any ideas?
Question FOCUS
The problem i'm trying to solve is how to submit status responses to web service urls dynamically without having any prior knowledge of them.
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.