اسم بروتوكول الخادم

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 مع صفة سلسلة واحدة: 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 مع صفة سلسلة واحدة: error. يتم ملء هذه الصفة بإخطاء يفسر الخطأ (ويمكن أن يتم عرضه في العميل في المستقبل).

بشأن تنفيذ المرجع، الوثيقة المرجحة هي:

{
    "error":"address not registred"
}

تسجيل اسم

يستخدم هذا الجزء من البروتوكول لتسجيل زوج اسم / عنوان جديد. يستخدم في السجل العام الرئيسي ولكن قد يكون اختياريًا في تنفيذ مخصص.

Request register

طلب تسجيل اسم foobar هو طلب POST مع /name/foobar كـ URI. يجب تعيين صفة العنوان Content-type إلى application/json.

جسم الطلب هو وثيقة JSON مع صفتين: addr و owner. addr تحتوي على معرف 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 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 مع صفات: success وهو boolean و 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 والتي هي مجموعة بولية ل false، name و addr والتي هي كل من السلاسل المكررة من الطلب الأصلي.

تسجيل foobar، مع تسجيله بالفعل، سيؤدي إلى رد فعل يلي:

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