Designing Evolvable Web APIs with ASP.NET

Appendix F. Media Type Specification for application/issue+json

During the lifecycle of many complex engineering projects and the subsequent maintenance of those products, we need to track the discovery and resolution of issues related to those projects. This media type specification describes a document format that has a very low barrier of entry for interoperability. The current specification is a minimal definition with the expectation that additional capabilities will be added over time.

Notational Conventions

The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119.

Issue Documents

The Issue document, shown in Example F-1, uses the format described in RFC 4627 and has the media type application/issue+json.

Example F-1. Minimal Issue document

{
        "title" : "This is a very simple issue"
}

Issue documents may contain the properties listed in Table F-1.

Table F-1. Semantics of properties

Property name	Description
id	A unique numeric identifier for the issue
title	A short textual summary of the issue (required)
description	A detailed description of the issue
status	A textual representation of the issue state containing one of the following values: open, closed.

issue+json also supports hypermedia using links that conform to the semantics of a link, as described by RFC 5988. Links are defined by a set of objects within an array named links.

Security Considerations

issue+json has some security ...