What happened to SSDS PUT/POST responses?

jcurrier — Fri, 25 Jul 2008 20:06:03 GMT

Since the rollout I've seen at least one or two messages regarding the altered responses we're now sending with the REST head of the service. There are several reasons why we've changed the service to now not return the entity body back to you again. These are as follows:

Version - Prior to this rollout the only mechanism that we had to communicate version information to you was via the entity body of the response (specifically the version element in the body). However, now that we have true ETag support we now can simply return this value back to caller via the ETag header per the Http spec.
Cost - Although at this point we don't charge for the service we eventually will. Included within this billing structure are charges for ingress & egress (bandwidth usage in essence). Therefore, by not returning the body to the caller (which the caller originally provided us with anyway) this is a net cost savings for you the caller.

Hope this helps to explain a bit more of the thinking behind the change. As always we're open to feedback.

--Jeff--

Optimistic Concurrency with SOAP in SSDS

jcurrier — Sun, 29 Jun 2008 23:47:00 GMT

In my last post I described how ETag's can be used in the upcoming sprint 3 version of SSDS. In this post I'd like to talk about how this same functionality is exposed through our SOAP service head.

In many ways designing this particular feature for the REST head was much easier than for the SOAP service head. This is because the Http specification describes, in a fair bit of detail, what the semantics are around things like ETag's. The SOAP specification provides no such guidance and as a result we've rolled our own implementation here to support this feature in a way that makes sense for our service.

VersionMatch

As I mentioned earlier, since there is no ETag concept natively in SOAP we've introduced a new object called, "VersionMatch". We've augmented the Scope struct in the system to now include this so that version is now also considered a qualifier for operations that take place via the SOAP service head.

The VersionMatch object, as shown in the class diagram below, captures two things. The first, is the version of the entity in question. This could be the version of the entity we've just created, the version that I, as a caller, want to retrieve, or finally the one I want to update or delete.

The second concept is something we refer to as the, "MatchType" or VersionMatchType. This is used to determine how the service should compare the version when executing the requested operation. This could mean that we only perform the operation if the version matches the version in the store (the VersionMatchType.Match case), or only perform the operation if it doesn't match (the VersionMatchType.NotMatch case) or finally to ignore the version completely when performing the operation. NOTE: By default we use the Ignore semantic unless otherwise instructed.

Class Diagram of the modified Scope object along with the new VersionMatch object and VersionMatchType enum.

Now, that we've covered a bit of the changes to how we address things in the system let's see how we can apply these new features to some common scenarios.

Conditional Get

Conditional retrieval is an interesting case if a mid-tier or client application is maintaining a cache. This shows up many times in the web browser case where large files are cached until they've been either refreshed or updated on the service side.

We can now perform a similar operation now using the SOAP service head. I've created a sample below which illustrates how a caller can now conditionally retrieve an entity only if the version has changed.

            using (SitkaSoapServiceClient client = new SitkaSoapServiceClient("SitkaSoapEndpoint"))
            {
                try
                {
                    // Create a reference to some entity that we know exists and one that
                    // we have a reference to in our cache (the version we have is 2000).
                    Scope entityScope = new Scope();
                    entityScope.AuthorityId = "some_authority";
                    entityScope.ContainerId = "some_container";
                    entityScope.EntityId = "123";
                    entityScope.VersionMatch = new VersionMatch();
                    entityScope.VersionMatch.Version = 2000;
                    entityScope.VersionMatch.MatchType = VersionMatchType.NotMatch;

                    // Then, retrieve the entity *only* if the version doesn't match the
                    // one that I already know about.
                    Entity theEntity = client.Get(entityScope);

                }
                catch (FaultException<Error> ex)
                {
                    if (ex.Detail.StatusCode == ErrorCodes.EntityNotModified)
                    {
                        // there is no later version.
                    }
                }
            }

Conditional Update and Delete

The next two cases are really very similar to one another. In both of these cases we really only want to update (or delete) the entity if we know that there has been no other modifications to the entity in question. This way we can be certain that we've not overwritten someone else's changes (in the update case) or perhaps deleted an entity which now (since the update) may not have needed to be deleted.

The code listing below illustrates both of these cases.

Conditional Update in SOAP

            using(SitkaSoapServiceClient client = new SitkaSoapServiceClient("SitkaSoapEndpoint"))
            {
                try
                {
                    // Create a reference to some entity that we know exists.
                    Scope entityScope = new Scope();
                    entityScope.AuthorityId = "some_authority";
                    entityScope.ContainerId = "some_container";
                    entityScope.EntityId = "123";

                    // Then, retrieve the entity (any version will do).
                    Entity theEntity = client.Get(entityScope);

                    // Update some properties on the Entity.
                    theEntity.Properties["FavoriteStorageService"] = "SSDS";

                    // Next, update the version match properties on the scope we'll be using to update
                    // the entity with.
                    entityScope.VersionMatch = new VersionMatch();
                    entityScope.VersionMatch.Version = theEntity.Version;
                    entityScope.VersionMatch.MatchType = VersionMatchType.Match;

                    // Finally, update the entity if the version check clears.
                    client.Update(entityScope, theEntity);

                }catch(FaultException<Error> ex)
                {
                    if(ex.Detail.StatusCode == ErrorCodes.PreconditionFailed)
                    {
                        // Our version check failed so we don't have the latest and greatest.
                    }
                }
            }

Conditional Delete in SOAP

            using(SitkaSoapServiceClient client = new SitkaSoapServiceClient("SitkaSoapEndpoint"))
            {
                try
                {
                    // Create a reference to some entity that we know exists.
                    Scope entityScope = new Scope();
                    entityScope.AuthorityId = "some_authority";
                    entityScope.ContainerId = "some_container";
                    entityScope.EntityId = "123";

                    // Next, set the version match properties on the scope we'll be using to remove
                    // the entity with.
                    entityScope.VersionMatch = new VersionMatch();
                    entityScope.VersionMatch.Version = 2000; // the version of the entity we know about.
                    entityScope.VersionMatch.MatchType = VersionMatchType.Match;

                    // Finally, remove the entity if the version check clears.
                    client.Delete(entityScope);

                }catch(FaultException<Error> ex)
                {
                    if(ex.Detail.StatusCode == ErrorCodes.PreconditionFailed)
                    {
                        // Our version check failed so we don't have the latest and greatest.
                    }
                }
            }

That covers the optimistic concurrency examples for the Sprint 3 bits of SSDS. I'm certain that there are other scenarios here that I'm not covering and I'd really like to hear other scenarios if you have them to share.

Next time, I'll cover perhaps the biggest feature of the sprint (and one of our most requested features of the service that we have now completed for sprint 3....). Look for more shortly :-)

Jeff's thoughts on Software Architecture, Large Scale Services and the Technical world at large : ETag

What happened to SSDS PUT/POST responses?

Optimistic Concurrency with SOAP in SSDS

VersionMatch

Conditional Get

Conditional Update and Delete