Web Services in C#: Payloads: PUT, POST, PATCH

Of course, we need to be able to send data to a web service via POST, PUT, or PATCH. All these web requests carry a payload: one or more items of data. How do we get these ApiController-based web services to accept data?

Defining Payload Classes

We’ll need to define a class to hold the incoming parameters. To do this for first and last name parameters, our class might look like this.

 public class Person {
   public string First { get; set; }
   public string Last { get; set; }
}

Notice how each parameter has its own class member. Notice how each member has a setter and getter. That’s because sometimes the ApiController code needs them.

The incoming parameter names are case-insensitive: first and last work just fine when a browser or a user of the web service sends them.

Now let’s use that class in a method

POST method

Here’s a POST method that uses our class.

public NegotiatedContentResult<string> Post([FromBody]Person person) {
  var name = person.First + " " + person.Last;
   if (string.IsNullOrWhiteSpace(name)) 
        return Content((HttpStatusCode) 400, "we need a name");
   return Content((HttpStatusCode) 200, name);
}

This method is like the GET method: it uses NegotiatedContentResult to return its results.

It tries to compose a name from the first and last name. If it can’t — if neither first nor last name arrived in the payload — it returns an error. Otherwise it returns the name. (This is a trivial example: it’s just for illustration.)

And, because the POST operation carries a payload this method has a parameter: [FromBody]Person person. The [FromBody] annotation tells dotnet to get the parameter’s value from, well, the body–the payload–of the POST operation.

These web service methods have only one parameter. When several different values are in the payload, each of them must be a member of the class in the parameter.

Using the POST method

This curl command sends a POST operation to the Post method.

curl -X POST -d "first=Buckaroo&last=Banzai" "localhost:64410/api/yoyo"

PUT and PATCH

In the way you get their parameters and send their results, POST, PUT, and PATCH work similarly. (Of course, for web services following the REST discipline, those three operations do different things.) In fact, you can use a single method for all three operations, like this:

[HttpPost, HttpPut, HttpPatch]
public NegotiatedContentResult<string> Post([FromBody]Person person) {
  var method = Request.Method;
  var name = person.First + " " + person.Last;
  if (string.IsNullOrWhiteSpace(name))
       return Content((HttpStatusCode)400, method + " request needs a name");
  return Content((HttpStatusCode)200, method + ": " + name);
}

Notice the list of [HttpPost, HttpPut, HttpPatch] attributes on the method. They define the operations the method accepts. Your code can retrieve the method actually used from Request.Method. It’s a string like POST, PUT, or PATCH.

Up Next

…