Content Types

ServiceStack supports the following formats:

.NET Service Clients

The different Content Types can be easily consumed using ServiceStack's Typed Generic Service Clients.

HTTP API Formats

ServiceStack Services supports a number of Content Negotiation options where you can define which format should be returned by adding a .{format} extension to your /route.{format}. Built-in Formats include:

  • .json
  • .xml
  • .jsv
  • .csv
  • .html

Example: http://web.web-templates.io/hello/World.json

Or by appending ?format={format} to the end of the URL:

  • ?format=json
  • ?format=xml
  • ?format=jsv
  • ?format=csv
  • ?format=html

Example: http://web.web-templates.io/hello/World?format=json

Alternatively ServiceStack also recognizes which format should be used with the Accept http header:

  • Accept: application/json
  • Accept: application/xml

Default Content-Type

The recommended way to request a specific content type is to add it to the Accept HTTP Request Header, e.g:

Accept: application/json

Alternatively you can specify to use a specific Content-Type as the default Content Type in your AppHost with:

SetConfig(new HostConfig {
     DefaultContentType = MimeTypes.Json 
});

Sometimes when calling web services from a web browser they'll ask for Accept: text/html and not JSON which by contract ServiceStack obliges by returning back HTML if it is enabled.

To ensure JSON is always returned you can disable the HTML support with:

SetConfig(new HostConfig {
    EnableFeatures = Feature.All.Remove(Feature.Html),
});

Pre-defined Routes 

/[xml|json|html|jsv|csv]/[reply|oneway]/[servicename]

Examples:

  • /json/reply/Hello (JSON)
  • /xml/oneway/SendEmail (XML)

Forcing a Content Type

Whilst ServiceStack Services are typically available on any endpoint and format, there are times when you only want adhoc Services available in a particular format, for instance you may only want the View Models for your dynamic Web Views available in HTML. This can now be easily enabled with the new [HtmlOnly] Request Filter Attribute, e.g:

[HtmlOnly]
public class HtmlServices : Service
{
    public object Any(MyRequest request) => new MyViewModel { .. };
}

This feature is also available for other built-in Content Types: [JsonOnly], [XmlOnly], [JsvOnly] and [CsvOnly].

Registering a Custom Format

Registering a custom format is done by registering the Format's Content-Type with to your AppHost's ContentTypes API, e.g:

//Register the 'text/csv' content-type format
//Note: Format is inferred from the last part of the content-type, e.g. 'csv'

public class CsvFormat : IPlugin
{
    public void Register(IAppHost appHost)
    {
        appHost.ContentTypes.Register(MimeTypes.Csv,
            SerializeToStream, 
            CsvSerializer.DeserializeFromStream);

        //ResponseFilter to add 'Content-Disposition' header for browsers to open in Spreadsheet
        appHost.GlobalResponseFilters.Add((req, res, dto) => {
            if (req.ResponseContentType == MimeTypes.Csv) {
                var fileName = req.OperationName + ".csv";
                res.AddHeader(HttpHeaders.ContentDisposition, 
                    $"attachment;{HttpExt.GetDispositionFileName(fileName)}");
            }
        });
    }

    void SerializeToStream(IRequest req, object request, Stream stream) =>
        CsvSerializer.SerializeToStream(request, stream);
}

We recommend encapsulating Custom Formats registrations into a Plugin as done with the built-in CsvFormat which is added by default:

Plugins.Add(new CsvFormat()); //added by default

Which makes it easy to register, detect and remove. E.g. to remove built-in support for CSV you can just remove it from the Plugins collection:

Plugins.RemoveAll(x => x is CsvFormat);

XmlSerializerFormat Plugin

The XmlSerializerFormat plugin changes ServiceStack to serialize XML with .NET XmlSerializer instead of .NET XML DataContractSerializer:

Plugins.Add(new XmlSerializerFormat());

The implementation provides a typical example of how to register or override different Content-Types in ServiceStack:

public class XmlSerializerFormat : IPlugin
{
    public static void Serialize(IRequest req, object response, Stream stream)
    {
        var serializer = new XmlSerializer(response.GetType());
        serializer.Serialize(stream, response);
    }

    public static object Deserialize(Type type, Stream stream)
    {
        var serializer = new XmlSerializer(type.GetType());
        var obj = (Type) serializer.Deserialize(stream);
        return obj;
    }

    public void Register(IAppHost appHost)
    {
        appHost.ContentTypes.Register(MimeTypes.Xml, Serialize, Deserialize);
    }
}

SOAP Endpoint

Consume ServiceStack Services via SOAP using WCF Add Service Reference or ServiceStack generic SOAP Clients.

MQ Endpoint

Consume ServiceStack Services via Message Queue.

Edit this page on GitHub