Skip to content

improve support for xml in accept #104

Description

@eviltester

I want Thingifier to recognise common XML-compatible media types,
so that API Challenges can demonstrate realistic XML content negotiation beyond only application/xml.

Background

Thingifier currently supports XML in a basic way using application/xml. It should expand XML support in the same spirit as JSON suffix support, so APIs can respond to generic XML, legacy XML, and vendor-specific XML media types where appropriate.

This should work with existing Accept header handling and should also be compatible with future q value negotiation.

Required Behaviour

Thingifier should treat these media types as valid XML requests for normal resource representations:

Accept: application/xml
Accept: text/xml
Accept: application/*+xml
Accept: application/vnd.apichallenges.todo+xml

For request bodies, Thingifier should also parse XML payloads when the request has:

Content-Type: application/xml
Content-Type: text/xml
Content-Type: application/vnd.apichallenges.todo+xml

Response Selection Rules

  • application/xml should return the existing XML representation.
  • text/xml should return the existing XML representation, with Content-Type: text/xml if the server chooses to echo the negotiated type.
  • application/*+xml should match supported structured XML media types, such as application/vnd.apichallenges.todo+xml.
  • application/vnd.apichallenges.todo+xml should return the normal todo XML representation, but with the vendor media type as the response Content-Type.
  • Unsupported XML-based media types should not automatically be treated as todo XML.

Do Not Treat These As Generic Todo XML

These are XML-based, but semantically different. They should only work if explicitly implemented for that purpose:

application/problem+xml
application/soap+xml
application/xhtml+xml
image/svg+xml
application/atom+xml
application/rss+xml

For example:

Accept: application/problem+xml

Should not return a normal todo list as XML. It should return 406 Not Acceptable unless the endpoint is intentionally returning a problem-details error response.

Examples

Accept: application/xml

Returns todo XML.

Accept: text/xml

Returns todo XML.

Accept: application/vnd.apichallenges.todo+xml

Returns todo XML using the vendor XML media type.

Accept: application/*+xml

Returns a supported +xml representation if one exists.

Accept: application/problem+xml

Does not return the normal todo XML representation.

Content-Type: application/vnd.apichallenges.todo+xml

Allows XML request body parsing for create/update endpoints if the body matches the normal todo XML shape.

Acceptance Criteria

  • Existing application/xml behaviour still works.
  • text/xml is accepted for XML response negotiation.
  • Vendor XML media types ending in +xml can be supported explicitly.
  • application/*+xml can match supported XML vendor types.
  • XML request bodies can be parsed from application/xml, text/xml, and supported vendor +xml content types.
  • application/problem+xml, application/soap+xml, application/xhtml+xml, image/svg+xml, application/atom+xml, and application/rss+xml are not treated as normal todo XML by default.
  • Tests cover Accept and Content-Type behaviour for generic XML, text XML, vendor XML, wildcard +xml, and unsupported XML-based media types.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions