CODEWITHSUNDEEP
rest
DiegoAlfonso
DiegoAlfonso

Reputation: 257

RESTful design workaround for an action that doesn't act over a resource

I have a piece of software I have to "APIfy". This software is written in COBOL and runing on a mainframe, and has only one entry point. The goal of the system is to evaluate a prospect customer by doing a risk assessment. It takes some customer information (such as SSN, first and last name) as parameter, asks some public and private entities for commercial background, runs a risk policy and gives an opinion.

I can't figure out how to design a RESTful API for this service (which is an architectural requirement; I can't write an RPC service). My first attempt was something like this:

POST mysoftwareapi/v0/evaluate

embedding the customer data in the HTTP body. But I discarded that one because it smells like RPC service (no resource; verb instead of noun).

Then I came out with a two-step API call:

POST mysoftwareapi/v0/prospect

and then

POST mysoftwareapi/v0/prospect/evaluate

or

GET mysoftwareapi/v0/prospect/evaluation

It looks a little more RESTful. But I don't want to persist a prospect before I have the evaluation result and the opinion is satisfactory (so the prospect becomes a customer).

What would be a good RESTful API design in this case?

Upvotes: 0

Views: 43

Answers (1)

Matt Timmermans
Matt Timmermans

Reputation: 59368

Well you certainly don't want to introduce persistence for no good reason. You should probably handle this similar to the way search is handled in restful APIs. Something like:

GET /mysoftwareapi/v0/evaluations?firstName=blablabla&lastName=blabla...

Or, if the params are too big or too sensitive to stick in an URL:

POST /mysoftwareapi/v0/evaluations

with the parameters in the entity body.

Is it RESTful? Well, at least the URL is a noun.

This can be part of an honest-to-goodness Roy Fielding REST API or not, depending on how the client software figures out how to use it and what it returns... But real REST APIs are not really what people want when they say they want REST APIs so don't sweat it too much. It'll be fine :)

Upvotes: 1

Related Questions