Creating Api Endpoints

Plugins are able to create their own api endpoints, whether it be for their own consumption, or for the purposes of publishing them to UI developers. This will demonstrate how to build an api endpoint.

Create the Service

Create a class that implements MediaBrowser.Model.Services.IService.

You will then have to create request dto classes that describe the request. The following is a complete service example:

[Route("/Weather", "GET")]
[Api(Description = "Gets weather information for a given location")]
public class GetWeather : IReturn<WeatherInfo>
{
    public string Location { get; set; }
}

public class WeatherService : IService
{
    public object Get(GetWeather request)
    {
        var result = GetWeatherInfo();

        return result;
    }
}

WeatherService is the service that processes the request. WeatherInfo is the dto that describes the parameters. The route attribute describes the url and http method.

The Get method should return an object that is one of the following:

• object to be serialized
• string (plain text)
• byte array (to be written to the response stream)
• stream (to be copied to the response stream)

Other http methods are supported - Post, Put, Delete, etc.

The Api and ApiMember attributes, as well as IReturn are all optional. They only serve to improve documentation.

Advanced Options

If you need http compression, response caching, or the ability to set custom response headers, extend your Service to implement IHasResultFactory. This will add a ResultFactory property of type IHttpResultFactory to your service.

The following are some of the methods available:

• GetResult
  Gets a result object with the ability to specify a content type and response headers.

• GetStaticFileResult
  Use this so serve a file statically from the file system.