Όνομα Προγραμματισμός του Server

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).

Κανόνες για τη διαμόρφωση ονομάτων

Τα ονόματα χρήστη ελέγχονται από έναν regex για να εξασφαλίσουν ορισμένους κανόνες σχετικά με τη μορφή τους:

  • Το μήκος πρέπει να είναι μεταξύ 3 και 32 χαρακτήρων

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

Αναζητώντας ένα όνομα

Αυτή είναι η κύρια υπηρεσία που παρέχεται από έναν διακομιστή ονομάτων.

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.

Στο παράδειγμα μας, η απάντηση JSON θα ήταν:

{
    "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.

Το σώμα είναι ένα έγγραφο JSON με 1 συρματολογικό χαρακτηριστικό: error. Αυτό το χαρακτηριστικό γεμίζεται με ένα μήνυμα σφάλματος που εξηγεί το σφάλμα (και θα μπορούσε να εμφανιστεί στο πελάτη στο μέλλον).

Για την εφαρμογή αναφοράς, το επιστροφικό έγγραφο είναι:

{
    "error":"name not registred"
}

Αναζήτηση διεύθυνσης

Αυτή η υπηρεσία είναι μια αναδρομική αναζήτηση. Αναζητάς μια διεύθυνση και ένα όνομα χρήστη επιστρέφεται αν ένα είναι εγγεγραμμένο στον διακομιστή ονομάτων.

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.

Το σώμα είναι ένα έγγραφο JSON με 1 συρματολογικό χαρακτηριστικό: name. Η τιμή αυτού του πεδίου είναι το όνομα που έχει καταχωριστεί σε αυτή τη διεύθυνση

Στο παράδειγμα μας, η απάντηση JSON θα ήταν:

{
    "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.

Το σώμα είναι ένα έγγραφο JSON με 1 συρματολογικό χαρακτηριστικό: error. Αυτό το χαρακτηριστικό γεμίζεται με ένα μήνυμα σφάλματος που εξηγεί το σφάλμα (και θα μπορούσε να εμφανιστεί στο πελάτη στο μέλλον).

Για την εφαρμογή αναφοράς, το επιστροφικό έγγραφο είναι:

{
    "error":"address not registred"
}

Καταχώριση ονόματος

Αυτό το μέρος του πρωτοκόλλου χρησιμοποιείται για την καταχώριση ενός νέου ζεύγους ονόματος/εύθυνσης.

Request register

Η αίτηση καταχώρισης του ονόματος foobar είναι μια αίτηση POST με /name/foobar ως URI.

Το σώμα του αιτήματος είναι ένα έγγραφο JSON με 2 συρματολογικά χαρακτηριστικά: addr και owner. addr περιέχει το ID Jami προθεσμία με 0x και owner είναι το όνομα που πρέπει να καταχωρηθεί.

Ένα παράδειγμα για foobar θα μπορούσε να είναι:

{
    "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.

Το σώμα περιέχει ένα έγγραφο JSON με 1 χαρακτηριστικό boolean success που ορίζεται σε true.

Για παράδειγμα:

{
    "success":true
}

Οι περαιτέρω προσπάθειες να αναζητηθεί το όνομα ή η διεύθυνση θα πρέπει να είναι επιτυχείς.

Response register (Bad request)

If the registration cannot 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.

Το σώμα είναι ένα έγγραφο JSON με 2 χαρακτηριστικά: success που είναι μια μπολ και error που είναι μια σειρά. success είναι ρυθμισμένο σε false και error είναι γεμάτο με ένα μήνυμα σφάλματος που εξηγεί το σφάλμα (και θα μπορούσε να εμφανιστεί στον πελάτη στο μέλλον).

Για άκυρη μορφοποίηση του ονόματος χρήστη, το σώμα μπορεί να είναι:

{
    "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.

Το σώμα είναι ένα έγγραφο JSON με 3 χαρακτηριστικά: success, το οποίο είναι ένα σύνολο boolean σε false, name και addr, τα οποία είναι και τα δύο συρματολόγια που αναπαράγονται από το αρχικό αίτημα.

Η καταχώριση foobar, εφόσον έχει ήδη καταχωρηθεί, θα οδηγούσε στην ακόλουθη απάντηση:

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