taldir

Directory service to resolve wallet mailboxes by messenger addresses
Log | Files | Refs | Submodules | README | LICENSE

swagger.json (16154B)

      1 {
      2     "components": {
      3         "schemas": {
      4             "taldir.AliasType": {
      5                 "properties": {
      6                     "challenge_fee": {
      7                         "description": "per challenge fee",
      8                         "type": "string"
      9                     },
     10                     "name": {
     11                         "description": "Name of the alias type, e.g. \"email\" or \"sms\".",
     12                         "type": "string"
     13                     }
     14                 },
     15                 "type": "object"
     16             },
     17             "taldir.Entry": {
     18                 "properties": {
     19                     "target_uri": {
     20                         "description": "Target URI to associate with this alias",
     21                         "type": "string"
     22                     }
     23                 },
     24                 "type": "object"
     25             },
     26             "taldir.ErrorDetail": {
     27                 "properties": {
     28                     "code": {
     29                         "description": "Numeric error code unique to the condition.\nThe other arguments are specific to the error value reported here.",
     30                         "type": "integer"
     31                     },
     32                     "currency": {
     33                         "description": "Name of the currency than was problematic (if applicable).",
     34                         "type": "string"
     35                     },
     36                     "detail": {
     37                         "description": "Optional detail about the specific input value that failed. May change without notice!",
     38                         "type": "string"
     39                     },
     40                     "hint": {
     41                         "description": "Human-readable description of the error, i.e. \"missing parameter\", \"commitment violation\", ...\nShould give a human-readable hint about the error's nature. Optional, may change without notice!",
     42                         "type": "string"
     43                     },
     44                     "index": {
     45                         "description": "Index of the argument that was bogus (if applicable).",
     46                         "type": "string"
     47                     },
     48                     "object": {
     49                         "description": "Name of the object that was bogus (if applicable).",
     50                         "type": "string"
     51                     },
     52                     "offset": {
     53                         "description": "Offset of the argument that was bogus (if applicable).",
     54                         "type": "string"
     55                     },
     56                     "parameter": {
     57                         "description": "Name of the parameter that was bogus (if applicable).",
     58                         "type": "string"
     59                     },
     60                     "path": {
     61                         "description": "Path to the argument that was bogus (if applicable).",
     62                         "type": "string"
     63                     },
     64                     "type_actual": {
     65                         "description": "Type that was provided instead (if applicable).",
     66                         "type": "string"
     67                     },
     68                     "type_expected": {
     69                         "description": "Expected type (if applicable).",
     70                         "type": "string"
     71                     }
     72                 },
     73                 "type": "object"
     74             },
     75             "taldir.RateLimitedResponse": {
     76                 "properties": {
     77                     "code": {
     78                         "description": "Taler error code, TALER_EC_TALDIR_REGISTER_RATE_LIMITED.",
     79                         "type": "integer"
     80                     },
     81                     "hint": {
     82                         "description": "The human readable error message.",
     83                         "type": "string"
     84                     },
     85                     "request_frequency": {
     86                         "description": "At what frequency are new registrations allowed. FIXME: In what? Currently: In microseconds",
     87                         "type": "integer"
     88                     }
     89                 },
     90                 "type": "object"
     91             },
     92             "taldir.RegisterMessage": {
     93                 "properties": {
     94                     "alias": {
     95                         "description": "Alias, in type-specific format",
     96                         "type": "string"
     97                     },
     98                     "duration": {
     99                         "description": "For how long should the registration last",
    100                         "type": "integer"
    101                     },
    102                     "target_uri": {
    103                         "description": "Target URI to associate with this alias",
    104                         "type": "string"
    105                     }
    106                 },
    107                 "type": "object"
    108             },
    109             "taldir.ValidationConfirmation": {
    110                 "properties": {
    111                     "solution": {
    112                         "description": "The solution is the SHA-512 hash of the challenge value\nchosen by TalDir (encoded as string just as given in the URL, but\nexcluding the 0-termination) concatenated with the binary 32-byte\nvalue representing the wallet's EdDSA public key.\nThe hash is provided as string in Crockford base32 encoding.",
    113                         "type": "string"
    114                     }
    115                 },
    116                 "type": "object"
    117             },
    118             "taldir.VersionResponse": {
    119                 "properties": {
    120                     "alias_type": {
    121                         "description": "Supported alias types",
    122                         "items": {
    123                             "$ref": "#/components/schemas/taldir.AliasType"
    124                         },
    125                         "type": "array",
    126                         "uniqueItems": false
    127                     },
    128                     "monthly_fee": {
    129                         "description": "fee for one month of registration",
    130                         "type": "string"
    131                     },
    132                     "name": {
    133                         "description": "Name of the protocol.",
    134                         "type": "string"
    135                     },
    136                     "version": {
    137                         "description": "libtool-style representation of the Merchant protocol version, see\nhttps://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning\nThe format is \"current:revision:age\".",
    138                         "type": "string"
    139                     }
    140                 },
    141                 "type": "object"
    142             }
    143         }
    144     },
    145     "info": {
    146         "contact": {
    147             "url": "https://taler.net"
    148         },
    149         "description": "The Taler Directory (TalDir) maps alias hashes to wallet URIs. Clients register an alias by completing an out-of-band challenge, then look it up later using the hashed alias.",
    150         "license": {
    151             "name": "AGPL-3.0-or-later",
    152             "url": "https://www.gnu.org/licenses/agpl-3.0.html"
    153         },
    154         "title": "Taler Directory API",
    155         "version": ""
    156     },
    157     "externalDocs": {
    158         "description": "",
    159         "url": ""
    160     },
    161     "paths": {
    162         "/config": {
    163             "get": {
    164                 "description": "Returns service metadata including the supported alias types and monthly fee.",
    165                 "responses": {
    166                     "200": {
    167                         "content": {
    168                             "application/json": {
    169                                 "schema": {
    170                                     "$ref": "#/components/schemas/taldir.VersionResponse"
    171                                 }
    172                             }
    173                         },
    174                         "description": "OK"
    175                     }
    176                 },
    177                 "summary": "Get service configuration",
    178                 "tags": [
    179                     "config"
    180                 ]
    181             }
    182         },
    183         "/register/{alias_type}": {
    184             "post": {
    185                 "description": "Starts the registration process for an alias. Sends an out-of-band challenge\nvia the specified validator (e.g. email or SMS). If the entry already exists\nwith no changes, returns the remaining validity instead.",
    186                 "parameters": [
    187                     {
    188                         "description": "Alias type (e.g. \\",
    189                         "in": "path",
    190                         "name": "alias_type",
    191                         "required": true,
    192                         "schema": {
    193                             "type": "string"
    194                         }
    195                     }
    196                 ],
    197                 "requestBody": {
    198                     "content": {
    199                         "application/json": {
    200                             "schema": {
    201                                 "oneOf": [
    202                                     {
    203                                         "type": "object"
    204                                     },
    205                                     {
    206                                         "$ref": "#/components/schemas/taldir.RegisterMessage",
    207                                         "summary": "body",
    208                                         "description": "Registration request"
    209                                     }
    210                                 ]
    211                             }
    212                         }
    213                     },
    214                     "description": "Registration request",
    215                     "required": true
    216                 },
    217                 "responses": {
    218                     "200": {
    219                         "content": {
    220                             "application/json": {
    221                                 "schema": {
    222                                     "properties": {
    223                                         "valid_for": {
    224                                             "type": "integer"
    225                                         }
    226                                     },
    227                                     "type": "object"
    228                                 }
    229                             }
    230                         },
    231                         "description": "Existing entry unchanged; returns remaining validity in microseconds"
    232                     },
    233                     "202": {
    234                         "content": {
    235                             "application/json": {
    236                                 "schema": {
    237                                     "type": "object"
    238                                 }
    239                             }
    240                         },
    241                         "description": "Challenge sent"
    242                     },
    243                     "400": {
    244                         "content": {
    245                             "application/json": {
    246                                 "schema": {
    247                                     "$ref": "#/components/schemas/taldir.ErrorDetail"
    248                                 }
    249                             }
    250                         },
    251                         "description": "Invalid request body or target URI"
    252                     },
    253                     "402": {
    254                         "description": "Payment required"
    255                     },
    256                     "404": {
    257                         "content": {
    258                             "application/json": {
    259                                 "schema": {
    260                                     "$ref": "#/components/schemas/taldir.ErrorDetail"
    261                                 }
    262                             }
    263                         },
    264                         "description": "Alias type not supported"
    265                     },
    266                     "429": {
    267                         "content": {
    268                             "application/json": {
    269                                 "schema": {
    270                                     "$ref": "#/components/schemas/taldir.RateLimitedResponse"
    271                                 }
    272                             }
    273                         },
    274                         "description": "Registration rate limit reached"
    275                     },
    276                     "500": {
    277                         "description": "Internal Server Error"
    278                     }
    279                 },
    280                 "summary": "Initiate alias registration",
    281                 "tags": [
    282                     "registration"
    283                 ]
    284             }
    285         },
    286         "/{h_alias}": {
    287             "get": {
    288                 "description": "Returns the target URI associated with the given hashed alias.",
    289                 "parameters": [
    290                     {
    291                         "description": "Crockford base32-encoded SHA-512 hash of the alias",
    292                         "in": "path",
    293                         "name": "h_alias",
    294                         "required": true,
    295                         "schema": {
    296                             "type": "string"
    297                         }
    298                     }
    299                 ],
    300                 "responses": {
    301                     "200": {
    302                         "content": {
    303                             "application/json": {
    304                                 "schema": {
    305                                     "$ref": "#/components/schemas/taldir.Entry"
    306                                 }
    307                             }
    308                         },
    309                         "description": "OK"
    310                     },
    311                     "404": {
    312                         "description": "Not Found"
    313                     }
    314                 },
    315                 "summary": "Look up an alias entry",
    316                 "tags": [
    317                     "entries"
    318                 ]
    319             },
    320             "post": {
    321                 "description": "Submits the solution to the out-of-band challenge to confirm the registration.",
    322                 "parameters": [
    323                     {
    324                         "description": "Crockford base32-encoded SHA-512 hash of the alias",
    325                         "in": "path",
    326                         "name": "h_alias",
    327                         "required": true,
    328                         "schema": {
    329                             "type": "string"
    330                         }
    331                     }
    332                 ],
    333                 "requestBody": {
    334                     "content": {
    335                         "application/json": {
    336                             "schema": {
    337                                 "oneOf": [
    338                                     {
    339                                         "type": "object"
    340                                     },
    341                                     {
    342                                         "$ref": "#/components/schemas/taldir.ValidationConfirmation",
    343                                         "summary": "body",
    344                                         "description": "Challenge solution"
    345                                     }
    346                                 ]
    347                             }
    348                         }
    349                     },
    350                     "description": "Challenge solution",
    351                     "required": true
    352                 },
    353                 "responses": {
    354                     "204": {
    355                         "description": "Registration confirmed"
    356                     },
    357                     "400": {
    358                         "content": {
    359                             "application/json": {
    360                                 "schema": {
    361                                     "$ref": "#/components/schemas/taldir.ErrorDetail"
    362                                 }
    363                             }
    364                         },
    365                         "description": "Invalid JSON"
    366                     },
    367                     "403": {
    368                         "description": "Wrong solution"
    369                     },
    370                     "404": {
    371                         "description": "Validation not found"
    372                     },
    373                     "429": {
    374                         "description": "Too many solution attempts"
    375                     },
    376                     "500": {
    377                         "description": "Internal Server Error"
    378                     }
    379                 },
    380                 "summary": "Complete alias registration",
    381                 "tags": [
    382                     "registration"
    383                 ]
    384             }
    385         }
    386     },
    387     "openapi": "3.1.0",
    388     "servers": [
    389         {
    390             "url": "/"
    391         }
    392     ]
    393 }