View Issue Details
| ID | Project | Category | View Status | Date Submitted | Last Update |
|---|---|---|---|---|---|
| 0004334 | Taler | documentation | public | 2016-03-22 17:56 | 2016-11-20 02:26 |
| Reporter | Marcello Stanisci | Assigned To | Marcello Stanisci | Resolution deadline | |
| Implementer | Reviewer | ||||
| Release signed by | Deployed by | ||||
| Verifier | Communicator | ||||
| Data protection authority notification required | No | ||||
| CSIRT notification required | No | ||||
| Estimated effort (hours) | Actual effort (hours) | 0 | |||
| Fast-track | No | ||||
| Work package | none | ||||
| Priority | normal | Severity | text | Reproducibility | have not tried |
| Status | closed | Resolution | fixed | ||
| Product Version | 0.0 | ||||
| Target Version | 0.2 | Fixed in Version | 0.2 | ||
| Summary | 0004334: Field types inconsistency | ||||
| Description | Throughout the API it's common having some JSON object description mentioning that one of its field is a EddsaPublicKey type. That leaves the reader disoriented for multiple reasons: 1 There is no specification of this type throughout the whole API 2 We put this type in JSON directly in base32 strings 3 In other parts the same object has just a 'string' type | ||||
| Tags | No tags attached. | ||||
| I suggest to assign the object a SomeType type and then link to the SomeType description where it's said that's actually a base32 encoding. Just note that this requires some change to the exchange API, but at least it saves us to say 'base32 encoding of ...' for any object field lying in this case | |
| I don't see why this would require any change to the exchange API, and I don't really understand what the problem is in the first place. EddsaPublicKey, when used in an interface declaration, is an alias for 'string'. Of course the documentation should link EddsaPublicKey to its definition, namely an alias to string. Are you suggesting to add an additional wrapper around every field that consists of a single string? Like { merchant_pub: {eddsa_public_key: "ABCD...." }, ...} this seems unnecessarily verbose and does not really help to improve the documentation or anything. | |
| I read Marcello as saying that first of all we describe the type inconsistently. IMO we should use "EddsaPublicKey" as the type, and then somewhere explain that all of these are Base32-encoded as strings. We should _not_ do the additional wrapping (first of all, due to inefficiency). | |
| We should discuss this one in-person. | |
| Whenever we mention Curve25519 keys/signatures, this should link to http://api.taler.net/api-common.html#public-keys and http://api.taler.net/api-common.html#signatures | |
| Date Modified | Username | Field | Change |
|---|---|---|---|
| 2016-03-22 17:56 | Marcello Stanisci | New Issue | |
| 2016-03-22 18:01 | Marcello Stanisci | Note Added: 0010313 | |
| 2016-03-23 13:25 | Florian Dold | Note Added: 0010323 | |
| 2016-03-23 16:17 | Christian Grothoff | Severity | minor => text |
| 2016-03-23 16:22 | Christian Grothoff | Note Added: 0010326 | |
| 2016-05-05 13:28 | Christian Grothoff | Status | new => acknowledged |
| 2016-05-05 13:28 | Christian Grothoff | Product Version | => 0.0 |
| 2016-05-05 13:28 | Christian Grothoff | Target Version | => 0.1 |
| 2016-05-05 13:28 | Christian Grothoff | Note Added: 0010647 | |
| 2016-05-31 13:16 | Christian Grothoff | Note Added: 0010815 | |
| 2016-09-27 20:28 | Christian Grothoff | Target Version | 0.1 => 0.2 |
| 2016-10-14 13:16 | Christian Grothoff | Status | acknowledged => informing |
| 2016-10-14 13:16 | Christian Grothoff | Fixed in Version | => 0.2 |
| 2016-10-14 13:16 | Christian Grothoff | Resolution | open => fixed |
| 2016-10-14 13:16 | Christian Grothoff | Assigned To | => Marcello Stanisci |
| 2016-11-20 02:26 | Christian Grothoff | Status | informing => closed |