Navne Server protokol

The protocol used by Jami to query and register a name is based on an HTTP REST API answering requests with JSON documents and regular HTTP status codes.

The public name server is hosted at ns.jami.net. Another implementation could use any other database or directory service making the name server protocol reusable.

If you run your own name server, looking up a username in the form of username@example.com will look up the name username with the name server at example.com (there is no need to add @ns.jami.net to use the default name server).

Regler for navneformatting

Brugernavne kontrolleres af en regex for at sikre nogle regler om deres format:

  • Længden skal være mellem 3 og 32 tegn

  • Those characters must be alphanumerical with dashes - being also accepted.

Spørgsmål om et navn

Dette er den vigtigste tjeneste, der leveres af en navneserver. Det gør det muligt at få Jami ID svarende til et brugernavn.

Request name

A request for the name foobar is a GET request with /name/foobar* as the URI.

Response name (Success)

If the name is found, a response with status code 200 OK must be sent to the client with a Content-type field set as application/json.

The body is a JSON documents with 2 string attributes : name and addr. name is equal to the one requested and addr is a hexadecimal representation of the Jami ID prefixed with 0x.

I vores eksempel ville svaret på JSON være:

{
    "name":"foobar",
    "addr":"0x29347542eb07159f316577e1ae16243d152f6b7b"
}

Response name (Not found)

If the name is not found, a response with status code 404 Not Found must be sent to the client with a Content-type field set as application/json.

Den er et JSON-dokument med 1 stregattribut: error. Dette atribut er fyldt med en fejlmeddelelse, der forklarer fejlen (og kan vises i klienten i fremtiden).

I forbindelse med referenceret er det returnerede dokument:

{
    "error":"name not registred"
}

Spørgsmål om adresse

Denne tjeneste er en omvendt søgning. Du spørger efter en adresse og et brugernavn returneres, hvis et er registreret på navneserveren.

Request address

A request for the ID jami:29347542eb07159f316577e1ae16243d152f6b7b is a GET request with /addr/29347542eb07159f316577e1ae16243d152f6b7b as the URI.

Response address (Success)

If the address corresponds to a username, a response with status code 200 OK must be sent to the client with a Content-type field set as application/json.

Den er et JSON-dokument med 1 strengattribut: name. Værdien af dette felt er navnet registreret på denne adresse

I vores eksempel ville svaret på JSON være:

{
    "name":"foobar"
}

Response address (Not found)

If the address is not found, a response with status code 404 Not Found must be sent to the client with a Content-type field set as application/json.

Den er et JSON-dokument med 1 stregattribut: error. Dette atribut er fyldt med en fejlmeddelelse, der forklarer fejlen (og kan vises i klienten i fremtiden).

I forbindelse med referenceret er det returnerede dokument:

{
    "error":"address not registred"
}

Registrering af et navn

Denne del af protokollen bruges til at registrere et nyt navn/adresspar.

Request register

En anmodning om registrering af navnet foobar er en POST anmodning med /name/foobar som URI. Overskriften atributten Content-type skal indsættes til application/json.

Anmodningens legeme er et JSON-dokument med 2 strengattributter: addr og owner. addr indeholder Jami ID med forkortelse 0x og owner er det navn, der skal registreres.

Et eksempel på foobar kan være:

{
    "addr":"0x29347542eb07159f316577e1ae16243d152f6b7b",
    "owner":"foobar"
}

Response register (Success)

If the name/address pair is successfully registered, a response with status code 200 OK must be sent to the client with a Content-type field set as application/json.

Kroppen indeholder et JSON-dokument med 1 boolean-attribut success indstillet på true.

Som eksempel:

{
    "success":true
}

Der bør derefter gøres yderligere forsøg på at søge efter navnet eller adressen.

Response register (Bad request)

If the registration is unable to be achieved because of an error in the request (formatting, missing attribute, etc.), a response with status code 400 Bad Request must be sent to the client with a Content-type field set as application/json.

Den er et JSON-dokument med 2 attributter: success, som er en boolean og error, som er en streng. success er indstillet på false og error er fyldt med en fejlmeddelelse, der forklarer fejlen (og kan vises i klienten i fremtiden).

For en ugyldig formatering af brugernavnet kan det være:

{
    "success": false,
    "error": "invalid name"
}

Response register (Forbidden)

If the registration cannot be achieved because the name is already taken, a response with status code 403 Forbidden must be sent to the client with a Content-type field set as application/json.

Den er et JSON-dokument med 3 attributter: success, som er et booleansk sæt til false, name og addr, som begge er strengene replikeret fra den oprindelige anmodning.

Registrering af foobar, når den allerede er registreret, vil føre til følgende svar:

{
    "success": false,
    "name":"foobar",
    "addr":"0x29347542eb07159fdeadbeefae16243d152f6b7b"
}