How do I publish the ASP.NET Web API model class definition?

Question

I'm trying to understand how or what options are available for publishing the model class that is passed to my ASP.NET Web API CRUD methods. Here is an example of my POST method.

public HttpResponseMessage PostMaterial(Material material)
{
    try
    {
        repository.Add(material);
    }
    catch (ArgumentNullException)
    {
        var exceptionResponse = Request.CreateResponse("Material object was null.");
        return exceptionResponse;
    }
    var response = Request.CreateResponse("Material " + material.MaterialName + " created.");
    string uri = Url.Link("DefaultApi", new { materialName = material.MaterialName });
    response.Headers.Location = new Uri(uri);
    return response;
}

In this example a material object is passed as a parameter when the method is called by an external API user. That caller would need a definition of the material class, so then could correctly build the object they will need to pass. If anyone has some details or a better explanation, then please let me know. I haven't had much luck finding an answer which leads me to believe I'm asking the wrong question.

Most of the research we have done leads us to believe that this is usually accomplished by generating Help pages. Similar to what is discussed here:http://stackoverflow.com/questions/18606715/asp-net-web-api-generate-all-parameters-from-model-help-pages In addition to that though, many of the groups consuming the Web API will be utilizing it in C#, so I'm trying to understand how to share the model class directly with applications consuming the API endpoints. In the event the class was changed it would be nice if the change was directly reflected to the calling applications. — Marc, Jul 22 '14 at 13:13

score 0 · Answer 1 · answered Jul 22 '14 at 14:26

I had the same situation and had two approaches:

Approach 1: Use help pages for web API

Approach 2: I can create a simple GET method which returns my model(blank or default values) in response. so they (caller) will know that what parameters/objects needs to send to consume the web api in their application.(but for this also i need to inform them about that method :) )

So, I choose the first approach as it is really helpful for external application developer to understand your web api properly. You can properly document your API also by using Web API help pages.

How do I publish the ASP.NET Web API model class definition?

1 Answers1