I have a web service that triggers some long operations on the server via asynchronous methods. Each operation has 3 methods:
One of them start the operation and immediately returns a ticket number.
One of them is called continuously from the client; it receives the ticket number and returns a boolean value, saying whether the operation is done.
The last one of them is called only after the operation is finished; it receives the ticket number and returns the result of the operation.
I'm not sure how to call this methods. I think about calling the methods something like this:
OperationName_Start
OperationName_IsReady
OperationName_GetResult
but I'm afraid I could be reinventing the wheel. Is there any well known naming convention for this usage pattern?
Its a shame you couldn't get an answer the first time around. I would strongly suggest reading this SOA Principles Link to gain a better understanding of the principals and importance of web service naming.
It's key to remember to name from the perspective of the consumer and maximise consumability and re-useability. Its also useful to remember that when you invoke a service, your are performing and action on an object i.e. you should have a verb and a noun. Also remember that web services are very very similar to functions in an object oriented language, so its helpful to think of what the code of the function of the web service would look like.
It's helpful to consider scenarios like:
What would happen if i changed the system the web service was calling?
Is there another scenario that could call this service?
How granular should the service be? What are the performance impacts of these decisions?
Without knowing the business context of what you are trying to achieve, we'll assume a basic example of submitting and electronic payment.
In this scenario, you may have:
ElectronicPayment_SendPayment (Note: the use of 'Send' keeping the business context, not the technical context; send could be via email, post, webservice. From your 'Start' example, what are you starting; here, the intent of the service is apparent)
ElectronicPayment_CheckStatus (Note: this is from the consumer's perspective. It's likely that checking processing status is a generic service, that could be seperated into something along the lines of CheckProcessingStatus (TicketNumber tN)
ElectronicPayment_RetrieveReciept (Note: Request/Response pattern with semantic link. Business Context of receipt and payment maintained)
Naming is highly contextual, and the above is not perfect, but hopefully it helps yourself and others who stumble upon this.
From the lack of answers, I assume that apparently there isn't a widely used standard on this issue, so it's OK to roll my own.
I chose to stick with:
OperationName_Start
OperationName_IsReady
OperationName_GetResult
Related
I got a query while developing rest service.
As per the REST design, GET is to read , PUT or POST are to create or update based on scenario , DELETE is to delete the resources.
But technically, Can't we perform a create or delete operation in GET call.
i.e. It is up to client way of calling by using specified URL pattern and required response type to hit the exact method in the service class of REST application. But why can't we perform a delete or create of some data in the GET service.
so my question is the DELETE or CREATE technically not possible in GET service or is it a rule to adhere to REST principles.
so my question is the DELETE or CREATE technically not possible in GET service or is it a rule to adhere to REST principles.
The latter. It is only a convention to use the DELETE HTTP method for delete operations. However using the GET HTTP method for delete operations is a bad idea. Below is a quote from "RESTful Java with JAX-RS 2.0, 2nd Edition" that explains why:
It is crucial that we do not assign
functionality to an HTTP method that supersedes the specification-defined boundaries
of that method. For example, an HTTP GET on a particular resource should be readonly.
It should not change the state of the resource it is invoking on. Intermediate services
like a proxy-cache, a CDN (Akamai), or your browser rely on you to follow the semantics
of HTTP strictly so that they can perform built-in tasks like caching effectively. If you
do not follow the definition of each HTTP method strictly, clients and administration
tools cannot make assumptions about your services, and your system becomes more
complex
so my question is the DELETE or CREATE technically not possible in GET
service or is it a rule to adhere to REST principles?
REST uses standards aka. uniform interface constraint. One of these standards is the HTTP standards which defines the HTTP methods. According to the HTTP standard the GET is a safe method:
In particular, the convention has been established that the GET and
HEAD methods SHOULD NOT have the significance of taking an action
other than retrieval. These methods ought to be considered "safe".
This allows user agents to represent other methods, such as POST, PUT
and DELETE, in a special way, so that the user is made aware of the
fact that a possibly unsafe action is being requested.
According to the RFC 2119:
SHOULD NOT - This phrase, or the phrase "NOT RECOMMENDED" mean that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.
For example write can be a side effect by GET, if you want to increase the visitor count by each request.
How the server software (API) is constructed and what 'rules' are applied is somewhat 'arbitrary'. Developers and their product managers could enforce 'rules' such as 'thou shalt not code or support DELETE operations through the GET operation', but in practice, that is not necessarily the main reason POST is chosen over GET. As others have mentioned, there may be assumptions based on the HTTP protocol that other vendors may rely on, but that is a rather complex and not necessarily relevant reasoning. For instance, your application may be built to connect directly to a server application, and another vendor's rules may not apply.
In a simpler example, on the world wide web and due to compliance and other factors, query string has a limited byte length. Because of this, operations that require a lot of data, such as a few very long encrypted data strings that might be needed for a DELETE operation in a database, GET may not be able to pass enough data, so POST may be the only viable option.
Custom built applications using a CuRL library might extend to include other RESTful operations with their intended functionality, but that would be for the benefit of the server API. Coding more operations on the client-side doesn't necessarily make things 'easier', 'faster', or necessarily 'more secure' from the client perspective, but doing so could help manage resources (a bit) on the server side and help maintain compatibility with third party software and appliances.
I am creating a REST-API and am encountering a problem where the client needs to get a calculation based on a lot of different parameters.
This GET operation might not be a part of any Save or Update operations (before the GET or after), and can happen in a stateless manner.
Due to this the GET URL can be very long (and even exceed the maximum allowed by the browser).
I have looked in other posts here in SO and elsewhere and it is discouraged to use a body in GET requests. But whats most important about all these posts is that none of them give an alternative to this problem they just state that something is flawed in the design ETC...ETC...
Well nothing is wrong with the design here. its a stateless calculation built on a lot of parameters.
I would like some alternatives. Thank you.
nothing is wrong with the design here
There is. From Wiki:
An important concept in REST is the existence of resources (sources of specific information), each of which is referenced with a global identifier (e.g., a URI in HTTP).
Your calculation parameters have nothing to do with the underlying resource identified by the URL you make the request to. You're not requesting an existing resource (as that's what GET is for, depending on how you're willing to interpret REST), but some calculations will be done based on some input. This is a Remote Procedure Call, not a REST call.
You can change your approach by modeling a Calculation, so you send a POST /Calculations/ request with all your parameters.
There's no requirement for a POST call to change server state (i.e. store the results):
httpbis-draft, POST (which is somewhat better worded and updated than RFC 2616):
The POST method requests that the target resource process the
representation enclosed in the request according to the resource's
own specific semantics.
POST is used for (among others): providing a block of data, such as the fields entered into an HTML
form, to a data-handling process;
So you can just return the calculation results along with a 200, or you can store them and return a 200, 201 or 204, containing or pointing to the calculation results, so you can retrieve them later, using GET /Calculations/$id.
As far as I can tell, the only solution you have left is to break the rules of REST and use a POST request. POST can have an arbitrary number of arguments, but it's meant for a "modification" operation in REST.
Like everything in software, the rules are there to help you avoid mistakes. But if the rules prevent you from solving your problems, you need to modify them a little bit (or modify them for a well defined part of your code).
Just make sure that everyone understands how you changed the rules, where the new rules apply (and where they don't). Otherwise, the next guy will "fix" your "broken" code with his simple test cases.
So you want a safe HTTP method that accepts a payload. Have a look at http://greenbytes.de/tech/webdav/draft-ietf-httpbis-method-registrations-14.html - both SEARCH and REPORT are theoretical candidates, if you can live with the WebDAV baggage they come with.
An alternative would be to start work on either generalizing these, or defining something new (but don't forget that definitions of new HTTP methods need IETF review, see http://greenbytes.de/tech/webdav/draft-ietf-httpbis-p2-semantics-25.html#considerations.for.new.methods.
I am reading about challenges of concurrent and networked software in pattern oriented software architecure vol 2.
Service access often involves invoking remote operations on resuable
components like OMG event service, etc. Supporting the static and
dynamic evolution of services and applications is antoher key
challenge in networked software system.
Evoution can occur in following way
Interfaces to and connectivity between component service roles can
change, often at run-time, and new service roles can be implemented
and installed into and installed into existing components.
It is even more challenging to determine how to access services that
are configured into a system 'on-demand' and whose implementations are
unknown when the system was designed origanally. Here design challenge
are two-fold.
First, an applicatoin must export new services, even though it may not know their detailed interfaces.
Second, an applicaiton must integrate these services into its own control flow and processing sequence transparently and robustly, even
at run-time.
I need your help in understanding above text by answering following questions.
What does author mean by "Interfaces to and connectivity between component service roles can change, often at run-time" ? Request to explain with easy to undestand example.
What does author mean by two points mentioned on-demand challenges which mentioned above. Request elobartion on above two points.
Thanks for your time and help.
1.What does author mean by "Interfaces to and connectivity between component service roles can change, often at run-time" ?
I'm not sure exactly. Interfaces change overtime because:
New technology standards can be adopted - say moving from SOAP to REST, or form XML to JSON, but that would happen slowly overtime through deployment - where as for me "runtime" is a memory space in which things run, and I don't see interfaces changing themselves taht fast - otherwise how could anyone integrate with them?
The API or interface contract itself changes to fulfill business need.
2.What does author mean by two points mentioned on-demand challenges which mentioned above.
Hmmm, good design patterns tend to survive time well (they never change, because they are never broken - like SOLID). The book you are refering to was written in 2000 I think - a lot has changed since then, so whilst the pattern may survive maybe the way we'd now describe it has changed (i.e what he means by "export new services" is open to interpretation)...
1.First, an application must export new services, even though it may not know their detailed interfaces.
Separation Of Concerns (basic OO stuff), all parts of your app don't (shouldn't) inherently know what the other parts are doing internally; likewise, as long as someone (including an external system) is satisfying the interface then who cares how it does so internally.
2.Second, an application must integrate these services into its own control flow and processing sequence transparently and robustly, even
at run-time.
I take this to mean that the program should never break, it should always compile, and if the application is dynamically creating and executing code (say based on user input) then there needs to be checks in-place so that the dynamic code doesn't break the app either.
Can someone point out the main differences between the two?
It seems that, at least conceptually, the two are very closely related. If I were to hazard a guess, I would say that the publish/subscribe method is a subset of the mediator pattern (since the mediator need not necessarily be used in the publish/subscribe manner, but the latter seems to require a sort of mediator object). Is that anywhere near close to it?
How I would describe the difference is that in mediator you probably care if the end application receives the message. So you use this to guarantee who is receiving the message. Whereas with pub/sub you just publish your message. If there are any subscribers they will get it but you don't care.
According to this page, the publish-subscribe model is an implementation of the mediator pattern.
Edit
I should note that the design patterns are called "patterns" precisely because there are going to be differences among every implementation. They aren't so much a set of decreed, canonical forms as they are a collection of observations on how people already write software. So there really isn't any way for a design to "strictly" adhere to a design pattern.
The implementation could be the same, but logically they are different (The difference is simple, but it is hard to see).
I'll explain it in a simple way below.
Pratically, in the implementation of the Publish/Subscribe pattern you will have at least an object with the methods "publish" and "subscribe".
But you can have also more of them, so the communication between components is not centralized by definition.
In the implementation of the Mediator pattern you will have JUST ONE object with methods "publish" and "subscribe". So the communication is "centralized" by definition.
In the GoF book, publish/subscribe is known as the Observer Pattern. The Mediator Pattern can be implemented using the Observer Pattern; but that is not the only way to implement a Mediator. The book describes this on page 278.
Colleague-Mediator communication. Colleagues have to communicate with their mediator when an event of interest occurs. One approach is to implement the Mediator as an Observer using the Observer pattern. Colleague classes act as Subjects, sending notifications to the mediator whenever they change state. The mediator responds by propagating the effects of the change to other colleagues.
Another approach defines a specialized notification interface in Mediator that lets colleagues be more direct in their communication... When communicating with the mediator, a colleague passes itself as an argument, allowing the mediator to identify the sender.
Note that even when implementing a Mediator as an Observer, it is described as communicating only among its colleagues whereas an Observer in general would likely communicate with other objects as well.
I think one main point of difference is the context of the problem.
Although a problem could be solved with either pattern, the real concerns are:
1: "How much change to bring about by the events are dependent on the general context ?"
2: "How frequently are the listeners expected to change?"
The classical case for the mediator pattern best illustrates this where you have a complex UI with a lot of components and the updation on each has a complex inter-dependency on the state of other similar components.
Although you can solve this problem with the pub/sub pattern; wherein your components listen for events and contain the logic necessary to update, the context object (along with the event) carry all necessary information. Here the advantage is obviously the proper encapsulation of logic pertaining to a component within itself. The downside is that if such components are supposed to change often then you have to replicate this logic fully in each new component you bring in.
To use a mediator is to introduce another layer and further abstract from the components. These components become thinner as they only deal with representation (UI look and feel) thus, become very easy to change. The only problem I have with this approach is that the updation logic now seems to spill to other components and any updation of the system would require one to change the component and the mediator if the component behavior is also to change.
That to me is the major dilemma/trade-off we need to solve. Please correct me if I haven't got anything correctly.
Our whole system is being designed around REST and are now considering how processes which are quite clearly RPC in intent can be mapped to RESTful resources without using verbs in the URL. Our remote procedure call is used to rebuild our search index when a content listing has been modified elsewhere.
What we are thinking about doing is this:
POST /index_updates
<indexUpdate><contentId>123</contentId></indexUpdate>
Nothing wrong with that in itself, but the smell is this resource which has been created does not return the URL of the newly created resource e.g. /index_updates/1234 which we can then access with a GET.
The indexing engine we are using does have a log mechanism, so in theory we could return a URL to a index_update resource so as to allow a GET to retrieve the resource, but to be honest we're not interested in the resource as this is nothing more than an RPC in disguise.
So my question is whether RESTfulness is expressed in structure or intent. I feel the structure of what I have outlined is restful, but the intent is not.
Does anyone have an comments or advice?
Thanks,
Chris
Use the right tool for the job. In this case, it definitely seems like the right tool is a pure remote procedure call, and there's no reason to pretend it's REST.
One reason you might return a new resource identifier from your POST /index_updates call is to monitor the status of the operation.
POST /index_updates
<contentId>123</contentId>
201 Created
Location: /index_updates/a9283b734e
GET /index_jobs/a9283b734e
<index_update><percent_complete>89</percent_complete></index_update>
This is obviously a subjective field, but GET PUT POST DELETE is a rich enough vocabulary to describe anything. And when I go to non-English-speaking Asian countries I just point and they know what I mean since I don't speak the language... but it's hard to really get into a nice conversation with someone...
It's not a bad idea to disguise RPC as REST, since that's the whole exercise. Personally, I think SOAP has been bashed and hated while in fact it has many strengths (and with HTTP compression, HTTP/SSL, and cookies, many more strengths)... and your app is really exposing methods for the client to call. Why would you want to translate that to REST? I've never been convinced. SOAP lets you use a language that we know and love, that of the programming interface.
But to answer your question, is it a bad idea to disguise RPC as REST? No. Disguising RPC as REST and translating to the four basic operations is what the thing is about. Whether you think that's cool or not is a different story.