Skip to content
This repository has been archived by the owner on Aug 20, 2024. It is now read-only.

RESTful API

Jump to bottom
Hendy Irawan edited this page Sep 26, 2015 · 34 revisions

Sanad RESTful API v0.1

Scenarios

Browser Add-on

  1. Add-on men-scan laman web yang sedang dibuka, sesuai struktur (karena bisa ada penyesuaian untuk beberapa struktur page yang dikenali, khususnya social media seperti Facebook, Twitter, atau software forum diskusi seperti vBulletin/phpBB), mengekstrak semua kalimat yang relevan
  2. Normalisasi kalimat tersebut sesuai kaidah bahasa: menstandarkan tanda baca, line ending, whitespace, kapitalisasi, dll.
    • Maksud dari sesuai kaidah bahasa, misalnya di bahasa Indonesia tidak mengenal huruf beraksen seperti "å" maka huruf-huruf tersebut diganti "a".
    • Untuk bahasa-bahasa yang dikenali di Eropa, dilakukan normalisasi aksen.
    • Untuk kaidah bahasa Arab, lakukan normalisasi tashkeel alias menjadi Arab gundul: "بِسْمِ ٱللهِ" menjadi "بسم الله", semua alif dinormalisasi jadi "ا"
    • Karakter yang tidak dikenali akan dibuang.
  3. TODO: Hash teks yang dinormalisasi, misal "zakat itu wajib" -> "z4 i2 w4". (see https://github.com/soluvas/sanad/issues/4)
  4. Kirim data teks ini ke server
  5. Cocokkan data dari server dengan struktur di sisi client
  6. Lakukan anotasi DOM HTML berdasarkan data yang match

Mobile app integration

  1. Kumpulkan teks ingin dicek
  2. Normalisasi teks tersebut sesuai kaidah bahasa (lihat "Browser add-on" untuk detail)
    • Optionally hashed
  3. Kirim data teks normalized/fingerprinted ini ke server
  4. Cocokkan data dari server dengan struktur di sisi client
  5. Tampilkan teks sesuai kebutuhan aplikasi dengan anotasi yang diterima

Web site / server-side integration

  1. Kumpulkan teks ingin dicek
  2. Normalisasi teks tersebut sesuai kaidah bahasa (lihat "Browser add-on" untuk detail)
    • Optionally hashed
  3. Kirim data teks normalized/fingerprinted ini ke server Sanad
  4. Cocokkan data dari server Sanad dengan struktur di sisi consumer
  5. Tampilkan teks atau lakukan pengolahan data sesuai kebutuhan consumer dengan anotasi yang diterima

Concepts

Logika Periwayatan

Sebetulnya logika periwayatan sangat relevan sekarang:

  1. matan... tujuannya/substansinya apa, jika tujuannya menjelek-jelekkan ini harus dianggap meragukan dan harus dilihat lebih lanjut
  2. rawi-nya, bagaimana kredibilitas sumber, apakah dikenal memilik bias? apakah pernah sengaja menyebarkan kebohongan (biar dng tujuan syiasah sekalipun)
  3. sanad, bagaimana rangkaian periwayatannya, apakah tersambung ke sumber utamanya, atau terputus. Imam Bukhari ra, mengimplementasikan metoda di atas atas 500.000 hadits dan hanya menerima 5000 buah.

Resources

annotate

Annotation Types

  1. TypeLink. a / rdfs:type link. This is an instance of the referenced class.
  2. SameAsLink. owl:sameAs link. This instance or class is a synonym of the other. Usually the referenced resource is the definitive one.
  3. Article / ScholarlyArticle / Hadith. A definitive narration. Every narration is an Articles, however can be promoted to ScholarlyArticle or Hadith by one or more testimonies. A Hadith is a subclass of ScholarlyArticle, e.g. using data from http://qaalarasulallah.com/
  4. Variation. A variation of one or more narration(s), the purpose is evaluated independently of the referenced narration(s).
  5. Scholar. Information about a person/scholar (can be deceased), which have been verified by an Person or Organization. e.g. using data from http://muslimscholars.info/
  6. Bibliography of a CreativeWork, e.g. Book, NewsArticle, etc.

Narrator Grades

The narrators of ahadith were broken up into different grades, ranks or levels based on whether or not ahadith could be accepted from them. Ibn Hajar al-'Asqalani placed the narrators into twelve ranks. The ranks as named and categorized by Ibn Hajar are widely accepted but not universal.

  1. companion. Companions: The first generation of Muslims did not need testimony to their knowledge or character as Allah the Most High has already done so in the Qur'an.
  2. trustworthiest. Awthaqun Nas (Thiqa Thiqa): These are the trustworthiest of people outside of the first generation of Muslims and this is the highest rank. They were learned scholars who were also of the most upright moral characters.
  3. trustworthy. Thiqat: These narrators are trustworthy in all areas including good retentive memory, but not to a superlative degree like those in the second rank.
  4. truthful. Saduq: truthful but less than rank three.
  5. honest. Saduq Yahim: Those who are trustworthy but who sometimes made mistakes in narrating ahadith, or have some delusion.
  6. acceptable. Maqbool/Layyin: Those who are accepted or acceptable. They transmitted a smaller number of ahadith, and we do not have proof against their reliability (or for them to be extraordinarily sound).
  7. uncertain. Majhool al-haal/Mastur (not Thiqa): Those whose situation is not precisely known. He had students who transmitted ahadith from him, but he does not have tawtheeq, or a testimony of trustworthiness, from the scholars of ahadith. There is nothing wrong with him from that which is apparent, but we don't really know anything about him.
  8. weak. Da'eef or weak: This means that there is nobody speaking positively on his behalf, and some of the scholars have spoken against him.
  9. unknown. Majhool or unknown: This is not the same as majhool al-haal. The majhool al-haal had more than one student narrate from him; the majhool is narrated from by only one individual, and we know nothing of him or his honesty.
  10. abandoned. Matruk or abandoned: This rank covers a few categories of narrators. This includes the one who committed many mistakes, the one who has detailed criticisms against him from the scholars, or one who did not meet the requirement for moral character. Also included here are the ones upon major sins (the fasiq) and the one who is unintelligent.
  11. accused. Muttaham bi'l kadhib: The one who was accused of lying and/or making up fake ahadith. The ahadith he narrates are considered batil.
  12. liar. Kadhdhaab, waddaa': This is the one who is actually called a liar or fabricator. Being labeled with such a title is not the same as merely being accused of committing those acts in some instances. The ahadith he narrates are considered mawdu' or fabricated.

Dokumentasi API

Dokumentasi teknis API ada di http://soluvas.github.io/sanad/

Response Schema

TODO: ganti dengan Swagger API docs

Struktur:

{
  "annotations": [ /* Annotation object */
      {
        id: "s0",
        hash: "z4 i2 w4",
        normalized: "zakat itu wajib",
        adoc: "_Zakat_ itu **wajib**.", /* Asciidoc syntax */
        html: "<em>Zakat</em> itu <strong>wajib</strong>.", /* HTML format */
        authenticity:
          "authentic" /* Ṣaḥīḥ (صَحِيْح)*/ |
          "good" /* Ḥasan (حَسَن) */ |
          "weak" /* Ḍaʻīf (ضَعِيْف) */
        purpose: "good" | "bad", /* matan */
        narrator: { /* rawi, Person object */
          "id": "hendy",
          "name": "Hendy Irawan"
        },
        successiveness: /* sanad/isnād. mashhur/aziz/gharib implies "singular" ahaad (آحاد) */
          "wording" | /* mutawatir (مُتَواتِر) in wording */
          "meaning" | /* mutawatir only in meaning, not wording */
          "triple" | /* mashhur (مَشْهُوْر) */
          "double" | /* aziz (عَزِيْز) */
          "single", /* gharib (غَرِيْب) */
        testimonies: [
          {
            "person": {
              "id": "febru",
              "name": "Febru Wasono"
            },
            "grade": "companion | ...", /* see Narrator Grades. the grade for the _topic at hand_, at the time of testimony */
            "creationTime": "2014-07-07T01:02:03+07:00",
            "place": "Kediri, East Java, Indonesia",
            "ip4": "202.132.x.x", /* full IPv4 address is logged by system, but only /32 is recorded */
            "ip6": "3ffe:1900:4545:3:x:x:x:x", /* full IPv6 address is logged by system, but only /32 is recorded */
            "proxy4": "202.100.120.130", /* optional. full IPv4 proxy address is logged and recorded */
            "proxy6": "3ffe:1900:4545:3:0:1:2:3" /* optional. full IPv6 proxy address is logged and recorded */
          },
          ...
        ] /* testimonies */
      },
      ...
  ]
}

Contoh:

curl -v -d normalized='taqobbalallahu minna wa minkum' sanad.sanad.amidea.dev:8980/annotation

> POST /annotation HTTP/1.1
> User-Agent: curl/7.35.0
> Host: sanad.sanad.amidea.dev:8980
> Accept: */*
> Content-Length: 41
> Content-Type: application/x-www-form-urlencoded
> 
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Content-Type: application/json;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Wed, 30 Jul 2014 17:38:53 GMT
< 

{
  "sections" : [ {
    "transliterations" : [ {
      "adoc" : "taqobbalallahu minna wa minkum",
      "html" : "taqobbalallahu minna wa minkum",
      "spellings" : [ {
        "claims" : [ ],
        "id" : "f4317c29-938b-48c3-9084-1a25fcb9870d",
        "description" : "lafadznya تقبل الله منا ومنكم",
        "descriptionHtml" : "lafadznya تقبل الله منا ومنكم",
        "spelling" : "formal"
      } ],
      "normalized" : "taqobbalallahu minna wa minkum",
      "numeronym" : null,
      "id" : "6716d949-cfde-4911-8efc-d058a286b1f5"
    } ]
  } ],
  "links" : [ ]
}

GET

Query parameters:

  • normalized (required, multiple cardinality), normalized text yang ingin di-annotate, misal "zakat itu wajib". Response masing-masing section disediakan secara berurutan.
  • format (optional): text | prefix (prefix numeronym) | numeronym (prefix & suffix numeronym)

POST

Sama seperti `GET tapi di Form Parameters, menggunakan form encoding.

Known Issues

Privacy

API versi 0.x ini masih memiliki kelemahan di sisi privacy, silakan berkontribusi ke https://github.com/soluvas/sanad/issues/4

Useful Links

Clone this wiki locally