Content Types

ServiceStack supports the following formats:

JSON
XML
CSV
JSV (hybrid CSV-style escaping + JSON format that is optimized for both size and speed)
SOAP 1.1/1.2 (requires ASP.NET Framework)
Message Pack
Protocol Buffers
HTML
- #Script Pages (Simple, clean, fast alternative to Razor)
- Razor (Microsoft's Razor View Engine)
- Markdown Razor (Razor-inspired syntax combined with markdown)
- HTML5 Report (Human-friendly HTML auto-layout to quickly visualize data returned by services)

.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);
    }
}