View Issue Details

IDProjectCategoryView StatusLast Update
0007174Talerotherpublic2024-08-12 09:59
ReporterFlorian Dold Assigned To 
PrioritynormalSeveritytextReproducibilityhave not tried
Status confirmedResolutionopen 
Target Versionpost-2.0 
Summary0007174: document conventions for HTTP Content-Type, consider allowing (or requiring?) document type versioning
DescriptionMost Taler services don't consistently enforce checks for the Content-Type header value. We just tend to assume that it's JSON.

We probably want to be more strict with this.

Generally, "application/json" should be appropriate, but doesn't allow versioning.

We could consider always requiring the following Content-Type header (and also consistently using it in the content negotiation for other requests):

  application/vnd.taler.$SERVICE+json;version=$CURRENT_VERSION"

The MIME type follows RFC 6839 (https://datatracker.ietf.org/doc/html/rfc6839).
TagsNo tags attached.

Activities

Christian Grothoff

2022-02-19 22:03

manager   ~0018704

I've filed an application for application/vnd.gnu.taler.exchange and application/vnd.gnu.taler.merchant with IANA at
https://www.iana.org/form/media-types -- let's see what they say.

ttn

2022-02-25 09:23

developer   ~0018720

Where would such documentation live?

Christian Grothoff

2022-03-01 00:23

manager   ~0018754

We've now registered the media types:
http://www.iana.org/assignments/media-types

ttn: I think the documentation for them should probably go into core/api-common.rst, as this is something across REST API calls.

ttn

2022-03-01 19:02

developer   ~0018759

@Christian Grothoff
IIUC the new types have required parameter "version".
To properly document this, i need to understand:
- What happens when that parameter is omitted?
- What happens when "version" is "too high" or "too low" (two different cases)?
- I assume that the vnd.gnu.taler.exchange is for communication w/ Exchange,
  while vnd.gnu.taler.merchant is for Merchant. Is that correct? Are there
  situations where both need to be involved at the same time?

I'm happy to look at source code if you have a pointer handy.

Christian Grothoff

2022-03-01 20:07

manager   ~0018760

Omitted: should be 400 Bad request.
Wrong range: I'd go for 501 Not implemented.
Yes, either merchant or exchange, never both. We may in the future request additional types for the auditor, sync and Anastasis.

Oh, and this is NOT implemented, we document -first- and then implement usually. So please document it, and then this bug should remain open until it is implemented!

Issue History

Date Modified Username Field Change
2022-02-10 20:57 Florian Dold New Issue
2022-02-10 21:06 Florian Dold Description Updated
2022-02-19 22:03 Christian Grothoff Note Added: 0018704
2022-02-25 09:23 ttn Assigned To => ttn
2022-02-25 09:23 ttn Status new => assigned
2022-02-25 09:23 ttn Note Added: 0018720
2022-03-01 00:23 Christian Grothoff Note Added: 0018754
2022-03-01 19:02 ttn Note Added: 0018759
2022-03-01 20:07 Christian Grothoff Note Added: 0018760
2022-11-08 15:12 Christian Grothoff Severity minor => text
2023-04-05 10:17 Florian Dold Target Version => post-1.0
2023-09-04 02:58 Christian Grothoff Assigned To ttn =>
2023-09-04 02:58 Christian Grothoff Status assigned => confirmed
2024-08-12 09:59 Christian Grothoff Target Version post-1.0 => post-2.0