On first sight, the architectural style of REST via HTTP seems to constrain us to simple CRUD APIs: We operate on „resources“ which we often map rather exactly to our internal domain- / entity-types and we also mainly use the HTTP-Verbs GET (=retrieve), POST = (=Create + Update partly), PUT (=Update/Replace) and DELETE. But how can this fit if we need to implement some kind of business logic like validation, that is not directly related to one of the CRUD-operations? I want to show you a real life example and explain how I solved the problem.

The real-life challenge: Detect the Porting-Status of a „PhoneNumberBlock“

The challenge I was facing was the following: Our telecom system has a PhoneNumberBlock-Entity, which describes the start and the end of a block of contiguous phone numbers, for example:

start = 8931144500

end = 8931144599

=> As you can see, this is a block consisting of 100 contiguous phone numbers.

When a customer requests a new telephone connection, he can specify one or more PhoneNumberBlocks, that need to be associated with the new connection. The blocks can have any arbitrary size. Among other things, the system has to check, if the requested block is currently ported to another carrier. It might well be, that the phone numbers of a requested block have differing porting status, because a PhoneNumberBlock has a limited lifetime. Let’s assume the above PhoneNumberBlock was once associated to a connection, but that connection has been terminated in the meantime. The block gets removed 3 months after termination and the numbers of the block might have been given away separately or in smaller blocks or even as part of a bigger block for other connections.

At some point, we need some logic that determines the current PortingStatus of the requested block with the following Enum-Values:

PORTED_AWAY_COMPLETELY

PORTED_AWAY_PARTLY

PORTED_AWAY_AS_PART_OF_BIGGER_BLOCK

COMPLETELY_AVAILABLE

The reason for this is, that the system must refuse the request if the PortingStatus is either PORTED_AWAY_PARTLY or PORTED_AWAY_AS_PART_OF_BIGGER_BLOCK.

Now the question is: How should this logic be properly designed with a RESTful API? What we have is a separate domain (a „porting-microservice“) that encapsulates the access to our database which contains all the porting information. From this database we must derive the above PortingStatus of the requested block.

First naive solution approach

As stated above, we have to think in terms of Resources and we only have the HTTP-Verbs, so the first idea was to offer a PortedPhoneNumberResource with a findAllPortedAwayPhoneNumbers() method.

GET http://myserver/rootcontext/resources/phonenumbers?status=portedAway

In this case, it would be the caller’s responsibility to search through the returned numbers to detect the correct overall state of the block. But this is a bad solution in terms of „separation of concerns“. The porting-microservice should not only deliver the data, it should – as far as possible – also implement the required logic around that data.

Second (still naive) solution approach with constrained find-Method

GET http://myserver/rootcontext/resources/phonenumbers?status=portedAway&start=8931144500&end=8931144599

Even if we constrain the find-method from the first solution with the start and end phone number of the requested block as query-parameters (findAllPortedAwayPhoneNumbersOfBlock), we still need the logic for finding out the status on the client side.

Third solution approach: The Status as a Resource

From the point of view of the client, it would be most desirable, if the REST-call could simply return the PortingStatus of the block. But then the PortingStatus would need to be a resource of its own. This doesn’t seem to make sense from a logical point of view, because a Status simply isn’t a resource.

Fourth solution approach: The Status as a Sub-Resource

What about a Sub-Resource? This seems to be more logical, but if we ask for a Sub-Resource in REST, we learned, that we need the ID of the parent resource, e.g.

GET http://myserver/rootcontext/resources/phonenumberblocks/1234/status

The problem is, that we don’t have the ID of the parent resource. Moreover, it is likely, that the block doesn’t even exist and thus there is in fact no ID that represents this block.

Are we stuck now? Can we throw away the RESTful style for things like this? The answer is „No!“.

Fifth and last solution approach: The Status as a Sub-Resource of a logical Resource

A requested block has a business key: the start- and the end phone number. Why don’t we concatenate the two numbers to a logical id including some separation character:

GET http://myserver/rootcontext/resources/phonenumberblocks/8931144500-8931144599/portingstatus

Maybe we could even optimize the logical id by just telling the starting number and the size of the block, but that’s syntactic sugar. Anyway, the Response-Body would simply contain the String-Representation of the actual PortingStatus.

This is in my opinion a good solution as it combines both the RESTful API design style and the „separation of concerns“ principle.

Conclusions