diff options
Diffstat (limited to 'core')
| -rw-r--r-- | core/api-merchant.rst | 2 | ||||
| -rw-r--r-- | core/api-taldir.rst | 163 |
2 files changed, 164 insertions, 1 deletions
diff --git a/core/api-merchant.rst b/core/api-merchant.rst index cadc1aa6..4142b049 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -118,7 +118,7 @@ such as the implemented version of the protocol and the currency used. **Response:** :http:statuscode:`200 OK`: - The exchange accepted all of the coins. The body is a `VersionResponse`. + The body is a `VersionResponse`. .. ts:def:: VersionResponse diff --git a/core/api-taldir.rst b/core/api-taldir.rst new file mode 100644 index 00000000..1493300c --- /dev/null +++ b/core/api-taldir.rst @@ -0,0 +1,163 @@ + + +``` +.. http:get:: /config + + Return the protocol version and currency supported by this service. + + **Response:** + + :http:statuscode:`200 OK`: + The body is a `VersionResponse`. + + .. ts:def:: VersionResponse + + interface VersionResponse { + // libtool-style representation of the Merchant protocol version, see + // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning + // The format is "current:revision:age". + version: string; + + // Name of the protocol. + name: "taler-directory"; + + // Supported registration methods + methods: Method; + + // fee for one month of registration + monthly_fee: Amount; + + } + + interface Method { + // Name of the method, e.g. "email" or "sms". + name: string; + + // per challenge fee + challenge_fee: Amount; + + } +``` +``` +.. http:post:: /register/$METHOD + + Endpoint to register, extend or modify the registration for an address in + the directory. + Where $METHOD is the type of address to register, e.g. "email", or "phone". + + **Request** + + .. ts:def:: IdentityMessage { + // Address, in $METHOD-specific format + address: string; + + // Public key of the user to register + public_key: EdDSAPublicKey; + + // (HTTPS) endpoint URL for the inbox service. + inbox_url: string; + + // For how long should the registration last. + duration: Time; + + // Order ID, if the client recently paid for this registration + order_id?: string; + } + + **Response** + + :http:statuscode:`200 Ok` + Registration already exists for this address for the specified duration. + Returns for how long this registration is paid for. + :http:statuscode:`202 Accepted` + Registration was initiated, the client should check for receiving + a challenge at the address where registration was attempted. + :http:statuscode:`402 Payment Required` + Client needs to make a Taler payment before proceeding. See + standard Taler payment procedure. + :http:statuscode:`429 Too Many Requests`: + The client exceeded the number of allowed attempts for initiating + a challenge for this address in the given timeframe. + The response format is given by `RateLimitedMessage`_. + + .. _RateLimitedMessage: + .. ts:def:: RateLimitedMessage + + interface RateLimitedMessage { + + // Taler error code, TALER_EC_TALDIR_REGISTER_RATE_LIMITED. + code: number; + + // At what frequency are new registrations allowed. + request_frequency: RelativeTime; + + // The human readable error message. + hint: string; + + } + + +``` +``` +.. http:get:: /register/$H_ADDRESS/$PINTAN + + Endpoint that generates an HTML Web site with a QR code and + taler://taldir/$H_ADDRESS/$PIN-wallet link for + completing the registration. Useful to open the registration + challenge in a browser (say if it was received on a different + device than where the wallet is running). + Does NOT complete the registration, as some providers automatically + click on all links in messages. Yes, privacy and so. + + Opening the link will lead the wallet to do the POST call below. + If the Taler wallet + can somehow intercept the URL (say for SMS, if it has the right + permissions) it can skip this request and directly do the POST. + +.. http:post:: /$H_ADDRESS + + Where $ID_KEY is the SHA-512 hash of the to be registered address in Crockford base32 encoding. + + **Request** + + .. ts:def:: IdentityConfirmation { + // The challenge ($PINTAN) value chosen by TalDir hashed + // with the wallet's public key. + solution: Hash; + + } + + **Response** + + :http:statuscode:`204 No Content`: + Registration complete. + :http:statuscode:`403 Forbidden`: + The solution is invalid. Retrying immediately is allowed. + :http:statuscode:`404 Not found`: + The address is unknown (original registration attempt may have expired). + :http:statuscode:`429 Too Many Requests`: + The client exceeded the number of allowed attempts for solving + a challenge for this address in the given timeframe. + +.. http:get:: /$H_ADDRESS + + **Response** + + Standard HTTP cache control headers are used to specify how long the + registration is still expected to be valid. + + :http:statuscode:`200 Ok`: + Registration information returned, of type `IdentityKey` + :http:statuscode:`404 Not found`: + The address is unknown (original registration attempt may have expired). + + + .. ts:def:: IdentityKey { + + // Registered public key of the user + public_key: EdDSAPublicKey; + + // (HTTPS) endpoint URL for the inbox service. + inbox_url: string; + + } |