1

I need to build a PUT method which will receive a insurance policy number and a star date of the relevant period. This method will update the start relevant period, so since there's an update, the method was defined as a PUT verb.

What would be the correct format for my method? I'm confused over two ways of possible correct formats:

http://<url>:<port>/api/valuation/<policy number>/<start date>

or

http://<url>:<port>/api/valuation/<policy number>

and receive the date from body?

In both cases, how do I declare the Route (I'm using .net framework 4.5)

For the option #1

[Route("UpdatePeriod/{numPolicy}/{startDate}")]
public IHttpActionResult UpdatePeriod(string numPolicy, string startDate)

For the option #2

[Route("UpdatePeriod/{numPolicy}")]
public IHttpActionResult UpdatePeriod(string numPolicy, [fromBody] string startDate)

Can someone give me a hint? I'm a little lost about this.

Thanks in advance.

Paul Carlton
  • 2,785
  • 2
  • 24
  • 42
Valmir Cinquini
  • 371
  • 7
  • 17

1 Answers1

1

It may come down to preference but what I would add is that it's really about organizing the URL in a logical way that makes sense using nouns and actions. So really it's about the most intuitive and reasonable representation of how your data works while following best practices and conventions.

So let us look at your examples.

http://<url>:<port>/api/valuation/<policy number>/<start date>

When I look at this it appears to me that this represents the data such that multiple insurance policies with the same policy number exist and you want to filter that down to one with the start date provided. I'm not sure how your data looks or if there should always be one valid insurance policy given a policy number but this wouldn't make much sense to me.

http://<url>:<port>/api/valuation/<policy number>

This suggests to me that there is one insurance policy given the policy number. This seems like the more likely scenario so I'll start with this one as scenario 1.

Scenario 1

If you know that you'll be acting upon one insurance policy that is valid given a policy number then it would not make sense to have the start date in the URL. You'll want it in the POST data you get through the body because you'll be acting upon that one insurance policy. #2 is your bet in this case and you'll want to make "valuation" plural.

Your URL's would look something like this:

# returns all insurance policies`
GET "http://<url>:<port>/api/valuations"

# returns one insurance policy with given policy number
GET "http://<url>:<port>/api/valuations/<policy number>"

# acts upon the insurance policy with that number, very broad
PUT "http://<url>:<port>/api/valuations/<policy number>"

# acts upon the insurance policy with number but in a more specific way with a dedicated method 
# start date would be in your post that you would then bind to a view model
PUT "http://<url>:<port>/api/valuations/<policy number>/startdate"

Scenario 2

If you know that you'll be fetching more than one insurance policy given an insurance policy number and want to filter that by the start date then it would make sense to have it in the URL. The URL would look something like this:

PUT http://<url>:<port>/api/valuations/<policy number>/startdate/<start date>

Why? Because you're acting on one insurance policy from a list of insurance policies with the same insurance policy number with differing start dates.

So your URL's would look something like this:

# returns all valuations insurance policies`
GET "http://<url>:<port>/api/valuations"

# returns list of insurance policies with the same policy number
GET "http://<url>:<port>/api/valuations/<policy number>"

# return one insurance policy with the policy number and start date
GET "http://<url>:<port>/api/valuations/<policy number>/startdate/<start date>"

# updating information for that ONE policy with policy number and start date
PUT "http://<url>:<port>/api/valuations/<policy number>/startdate/<start date>"

I am basing my answer off noun based API urls and not verb based. For more on this: Confusion Between Noun vs. Verb in Rest URLs

If you're passing start date as a POST parameter you should probably have that bound to a view model: 
class ValuationPolicyStartDateViewModel
{
   public DateTime? StartDate { get; set; }
}

// then in your controller
// PUT StartDate = "01/22/2018" will then be bound to your  view model
public IHttpActionResult UpdatePolicyByStartDate(string policyNumber, [FromBody] ValuationPolicyStartDateViewModel viewModel)
{
   ... code that validates etc ...
}

TL;DR

If /api/valuation/<policy number> returns 1 insurance policy, go with option 2 in your examples and make "valuation" plural.

If /api/valuation/<policy number> returns more than 1 insurance policy then you should do a couple things: change valuation to valuations and add startdate as a filter variable.

Paul Carlton
  • 2,785
  • 2
  • 24
  • 42