Gambaran Umum REST API

Platform TechMaju secara otomatis menghasilkan REST API untuk semua DocType Anda, memungkinkan Anda menjalankan metode Python secara acak menggunakan jalur modul bertitiknya.

Metode Autentikasi

Ada tiga cara utama untuk melakukan autentikasi melalui REST API TechMaju:

Autentikasi Berbasis Token:

• Generate API Key dan API Secret:

  1. Arahkan ke Daftar Pengguna dan pilih pengguna.

  2. Klik tab "Pengaturan" (jika berlaku).

  3. Perluas bagian Akses API dan klik "Generate Keys".

  4. Salin API Secret dan simpan dengan aman.

  5. Catat API Key di bagian yang sama.

• Gabungkan api_key dan api_secret dengan tanda titik dua : dan kirim token api_key:api_secret ke header Otorisasi dalam permintaan Anda:

javascript

fetch('http://<base-url>/api/method/service-resource', {
    headers: {
        'Authorization': 'token api_key:api_secret'
    }
})
.then(r => r.json())
.then(r => {
    console.log(r);
})

sh

curl http://<base-url>/api/method/service-resource -H "Authorization: token api_key:api_secret"

Autentikasi Berbasis Password:

• Autentikasi dengan username dan password, yang bergantung pada cookies dan data sesi:

javascript

fetch('http://<base-url>/api/method/login', {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        usr: 'username atau email',
        pwd: 'password'
    })
})
.then(r => r.json())
.then(r => {
    console.log(r);
})

sh

curl --cookie-jar snowcookie --request POST "http://<base-url>/api/method/login" -H 'Content-Type: application/json' -H 'Accept: application/json' --data-raw "{ \"usr\" : \"<username>\", \"pwd\": \"<password>\" }"

Autentikasi Berbasis Access Token:

• Gunakan OAuth untuk menghasilkan access_token sesuai dokumentasi.

• Pasang access_token di header Otorisasi dalam permintaan Anda:

javascript

fetch('http://<base-url>/api/method/service-resource', {
    headers: {
        'Authorization': 'Bearer access_token'
    }
})
.then(r => r.json())
.then(r => {
    console.log(r);
})

Mendapatkan Daftar Dokumen

Untuk mendapatkan daftar record untuk DocType, kirim permintaan GET ke /api/resource/:doctype. Secara default, ini mengembalikan 20 record dengan hanya nama mereka:

GET /api/resource/:doctype
Response:
{
  "data":[
    {"name":"f765eef382"},
    {"name":"2a26fa1c64"},
    //...
  ]
}

Parameter Fields

Anda dapat menentukan field mana yang ingin diambil menggunakan parameter fields:

GET /api/resource/:doctype?fields=["field1", "field2"]
Response:
{
  "data":[
    {"description":"Teks Deskripsi","name":"f765eef382"},
    //...
  ]
}

Parameter Filters

Anda dapat memfilter record menggunakan parameter filters. Filters harus ditentukan sebagai array, di mana setiap filter menggunakan format: [field, operator, value].

GET /api/resource/:doctype?filters=[["field1", "=", "value1"], ["field2", ">", "value2"]]
Response:
{
  "data":[
    {"name":"f765eef382"},
    //...
  ]
}

Parameter filters menggabungkan semua filter yang ditentukan menggunakan operator SQL AND. Jika Anda memerlukan filter OR, Anda dapat menggunakan parameter or_filters. Sintaks untuk or_filters sama dengan filters.

Parameter Order_by

Anda juga dapat menentukan field dan urutan pengurutan menggunakan parameter order_by. Harus menggunakan format fieldname asc atau fieldname desc. Spasi harus dienkode dalam URL:

GET /api/resource/:doctype?order_by=title%20desc

Parameter Limit

Anda dapat melakukan paging pada hasil dengan menyediakan parameter limit_start dan limit:

GET /api/resource/:doctype?limit_start=5&limit=10
Response:
{
  "data": [
    {"name":"6234d15099"},
    //...
  ]
}

Mengambil sebagai List

Secara default, Anda akan menerima data sebagai List[dict]. Anda dapat mengambil data Anda sebagai List[List] dengan mengirimkan as_dict=False:

GET /api/resource/:doctype?limit_start=5&limit=5&as_dict=False
Response:
{
  "data": [
    ["6234d15099"],
    //...
  ]
}

Debug

Untuk debug query yang dibangun untuk permintaan Anda, Anda dapat mengirimkan debug=True dengan permintaan. Ini mengembalikan query yang dijalankan dan waktu eksekusi di bawah exc dari payload:

GET /api/resource/:doctype?limit_start=10&limit=5&debug=True
Response:
{
  "data": [
    {"name":"4bcf8b701c"},
    //...
  ],
  "exc": "[\"select `tabToDo`.`name`\\n\\t\\t\\tfrom `tabToDo`\\n\\t\\t\\t\\n\\t\\t\\t order by `tabToDo`.`modified` DESC\\n\\t\\t\\tlimit 5 offset 10\", \"Execution time: 0.0 sec\"]"
}

Operasi CRUD

TechMaju menyediakan endpoint untuk operasi CRUD untuk semua DocType. Pastikan header disetel untuk respon JSON:

{
    "Accept": "application/json",
    "Content-Type": "application/json",
}

Create

POST /api/resource/:doctype

POST /api/resource/:doctype
Body: {"description": "New ToDo"}
Response:
{
  "data": {
    "name": "af2e2d0e33",
    "owner": "Administrator",
    "creation": "2019-06-03 14:19:00.281026",
    "modified": "2019-06-03 14:19:00.281026",
    "modified_by": "Administrator",
    "idx": 0,
    "docstatus": 0,
    "status": "Open",
    "priority": "Medium",
    "description": "New ToDo",
    "doctype": "ToDo"
  }
}

Read

GET /api/resource/:doctype/:name

GET /api/resource/:doctype/:name
Response:
{
  "data": {
    "name": "bf2e760e13",
    "owner": "Administrator",
    "creation": "2019-06-03 14:19:00.281026",
    "modified": "2019-06-03 14:19:00.281026",
    "modified_by": "Administrator",
    "idx": 0,
    "docstatus": 0,
    "status": "Open",
    "priority": "Medium",
    "description": "<p>Deskripsi Test</p>",
    "doctype": "ToDo"
  }
}

Update

PUT /api/resource/:doctype/:name

PUT /api/resource/:doctype/:name
Body: {"description": "Deskripsi Baru"}
Response:
{
  "data": {
    "name": "bf2e760e13",
    "owner": "Administrator",
    "creation": "2019-06-03 14:19:00.281026",
    "modified": "2019-06-03 14:21:00.785117",
    "modified_by": "Administrator",
    "idx": 0,
    "docstatus": 0,
    "status": "Open",
    "priority": "Medium",
    "description": "Deskripsi Baru",
    "doctype": "ToDo"
  }
}

Delete

DELETE /api/resource/:doctype/:name

DELETE /api/resource/:doctype/:name
Response: {"message": "ok"}

Pemanggilan Metode Jarak Jauh

TechMaju memungkinkan Anda memicu endpoint REST API untuk menangani logika khusus.

GET /api/method/service-resource
Response:
{
  "message": "Hello World"
}

Jika metode Anda mengembalikan beberapa nilai, Anda harus mengirimkan permintaan GET.

Jika metode Anda mengubah status database, gunakan POST. Setelah permintaan POST berhasil, framework akan secara otomatis memanggil frappe.db.commit() untuk menyimpan perubahan ke database.

Respon yang berhasil akan mengembalikan objek JSON dengan kunci message.

Respon yang error akan mengembalikan objek JSON dengan kunci exc yang berisi stack trace dan exc_type yang berisi Exception yang dilemparkan.

Nilai yang dikembalikan oleh metode akan dikonversi ke JSON dan dikirim sebagai respon.

Upload File

Ada metode khusus /api/method/upload_file yang menerima data file biner dan mengunggahnya ke dalam sistem.

Berikut adalah perintah curl untuk itu:

sh

curl -X POST http://<base-url>/api/method/upload_file -H 'Accept: application/json' -H 'Authorization: token xxxx:yyyy' -F file=@/path/to/file/file.png

Jika Anda menggunakan JavaScript sisi klien untuk mengunggah file, Anda dapat menambahkan file yang diunggah sebagai FormData dan mengirimkan permintaan XHR. Berikut adalah kode implementasi di Frappe Desk:

javascript

var formData = new FormData();
formData.append('file', fileInputElement.files[0]);

var xhr = new XMLHttpRequest();
xhr.open('POST', '/api/method/upload_file', true);
xhr.setRequestHeader('Accept', 'application/json');
xhr.setRequestHeader('Authorization', 'token xxxx:yyyy');
xhr.onload = function () {
    if (xhr.status === 200) {
        var response = JSON.parse(xhr.responseText);
        console.log(response);
    } else {
        console.error(xhr.statusText);
    }
};
xhr.send(formData);

Praktik Terbaik: Klien vs Server

Bergantung pada apakah endpoint API bersifat internal atau eksternal, disarankan untuk menggunakan artefak sisi klien atau sisi server, masing-masing.