Langkah Pertama¶

File ReadyAPI yang paling sederhana bisa seperti berikut:

Python 3.8+

from readyapi import ReadyAPI

app = ReadyAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

Salin file tersebut ke main.py.

Jalankan di server:

$ <font color="#4E9A06">readyapi</font> dev <u style="text-decoration-style:single">main.py</u>
<font color="#3465A4">INFO    </font> Using path <font color="#3465A4">main.py</font>
<font color="#3465A4">INFO    </font> Resolved absolute path <font color="#75507B">/home/user/code/awesomeapp/</font><font color="#AD7FA8">main.py</font>
<font color="#3465A4">INFO    </font> Searching for package file structure from directories with <font color="#3465A4">__init__.py</font> files
<font color="#3465A4">INFO    </font> Importing from <font color="#75507B">/home/user/code/</font><font color="#AD7FA8">awesomeapp</font>

 ╭─ <font color="#8AE234"><b>Python module file</b></font> ─╮
 │                      │
 │  🐍 main.py          │
 │                      │
 ╰──────────────────────╯

<font color="#3465A4">INFO    </font> Importing module <font color="#4E9A06">main</font>
<font color="#3465A4">INFO    </font> Found importable ReadyAPI app

 ╭─ <font color="#8AE234"><b>Importable ReadyAPI app</b></font> ─╮
 │                          │
 │  <span style="background-color:#272822"><font color="#FF4689">from</font></span><span style="background-color:#272822"><font color="#F8F8F2"> main </font></span><span style="background-color:#272822"><font color="#FF4689">import</font></span><span style="background-color:#272822"><font color="#F8F8F2"> app</font></span><span style="background-color:#272822">  </span>  │
 │                          │
 ╰──────────────────────────╯

<font color="#3465A4">INFO    </font> Using import string <font color="#8AE234"><b>main:app</b></font>

 <span style="background-color:#C4A000"><font color="#2E3436">╭────────── ReadyAPI CLI - Development mode ───────────╮</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│  Serving at: http://127.0.0.1:8000                  │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│  API docs: http://127.0.0.1:8000/docs               │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│  Running in development mode, for production use:   │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│  </font></span><span style="background-color:#C4A000"><font color="#555753"><b>readyapi run</b></font></span><span style="background-color:#C4A000"><font color="#2E3436">                                        │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">╰─────────────────────────────────────────────────────╯</font></span>

<font color="#4E9A06">INFO</font>:     Will watch for changes in these directories: [&apos;/home/user/code/awesomeapp&apos;]
<font color="#4E9A06">INFO</font>:     Uvicorn running on <b>http://127.0.0.1:8000</b> (Press CTRL+C to quit)
<font color="#4E9A06">INFO</font>:     Started reloader process [<font color="#34E2E2"><b>2265862</b></font>] using <font color="#34E2E2"><b>WatchFiles</b></font>
<font color="#4E9A06">INFO</font>:     Started server process [<font color="#06989A">2265873</font>]
<font color="#4E9A06">INFO</font>:     Waiting for application startup.
<font color="#4E9A06">INFO</font>:     Application startup complete.

Di output, terdapat sebaris pesan:

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Baris tersebut menunjukan URL dimana app aktif di komputer anda.

Mencoba aplikasi¶

Buka browser di http://127.0.0.1:8000.

Anda akan melihat response JSON sebagai berikut:

{"message": "Hello World"}

Dokumen API interaktif¶

Sekarang kunjungi http://127.0.0.1:8000/docs.

Anda akan melihat dokumentasi API interaktif otomatis (dibuat oleh Swagger UI):

Swagger UI

Dokumen API alternatif¶

Dan sekarang, kunjungi http://127.0.0.1:8000/redoc.

Anda akan melihat dokumentasi alternatif otomatis (dibuat oleh ReDoc):

ReDoc

OpenAPI¶

ReadyAPI membuat sebuah "schema" dimana semua API anda menggunakan standar OpenAPI untuk mendefinisikan API.

"Schema"¶

"schema" adalah suatu definisi atau deskripsi dari sesuatu. Bukan kode yang mengimplementasi definisi tersebut. Ini hanyalah sebuah deskripsi abstrak.

"schema" API¶

Dalam hal ini, OpenAPI adalah spesifikasi yang menunjukan bagaimana untuk mendefinisikan sebuah skema di API anda.

Definisi skema ini termasuk jalur API anda, parameter yang bisa diterima, dll.

"schema" Data¶

Istilah "schema" bisa juga merujuk ke struktur data, seperti konten JSON.

Dalam kondisi ini, ini berarti attribut JSON dan tipe data yang dimiliki, dll.

Schema OpenAPI and JSON¶

"schema" OpenAPI mendefinisikan skema API dari API yang anda buat. Skema tersebut termasuk definisi (atau "schema") dari data yang dikirim atau diterima oleh API dari JSON Schema, skema data standar JSON.

Lihat `openapi.json`¶

Jika anda penasaran bagaimana skema OpenAPI polos seperti apa, ReadyAPI secara otomatis membuat JSON (schema) dengan deksripsi API anda.

anda bisa melihatnya di: http://127.0.0.1:8000/openapi.json.

Anda akan melihat JSON yang dimulai seperti:

{
    "openapi": "3.1.0",
    "info": {
        "title": "ReadyAPI",
        "version": "0.1.0"
    },
    "paths": {
        "/items/": {
            "get": {
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {



...

Kegunaan OpenAPI¶

Skema OpenAPI adalah tulang punggung dua sistem dokumentasi API interaktif yang ada di ReadyAPI.

Ada banyak alternatif sistem dokumentasi lainnya yang semuanya berdasarkan OpenAPI. Anda bisa menambahkannya ke aplikasi ReadyAPI anda.

Anda juga bisa menggunakan OpenAPI untuk membuat kode secara otomatis, untuk klien yang menggunakan API anda. Sebagai contoh, frontend, aplikasi mobile atau IoT.

Ringkasan, secara bertahap¶

Langkah 1: impor `ReadyAPI`¶

Python 3.8+

from readyapi import ReadyAPI

app = ReadyAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

ReadyAPI adalah class Python yang menyediakan semua fungsionalitas API anda.

Detail Teknis

ReadyAPI adalah class turunan langsung dari Starlette.

Anda bisa menggunakan semua fungsionalitas Starlette dengan ReadyAPI juga.

Langkah 2: buat "instance" dari `ReadyAPI`¶

Python 3.8+

from readyapi import ReadyAPI

app = ReadyAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

Di sini variabel app akan menjadi sebuah "instance" dari class ReadyAPI.

Ini akan menjadi gerbang utama untuk membuat semua API anda.

Langkah 3: Buat operasi path¶

Path¶

"Path" atau jalur di sini merujuk ke bagian URL terakhir dimulai dari / pertama.

Sehingga, URL seperti:

https://example.com/items/foo

...path-nya adalah:

/items/foo

Info

"path" juga biasa disebut "endpoint" atau "route".

ketika membuat API, "path" adalah jalan utama untuk memisahkan "concern" dan "resources".

Operasi¶

"Operasi" di sini merujuk ke salah satu dari metode HTTP berikut.

Salah satu dari:

POST
GET
PUT
DELETE

...dan operasi lainnya yang unik:

OPTIONS
HEAD
PATCH
TRACE

Dalam protokol HTTP, anda bisa berkomunikasi ke setiap path menggunakan satu (atau lebih) metode di atas.

Ketika membuat API, anda umumnya menggunakan metode HTTP tertentu untuk proses tertentu.

Umumnya menggunakan:

POST: untuk membuat data.
GET: untuk membaca data.
PUT: untuk memperbarui data.
DELETE: untuk menghapus data.

Sehingga, di OpanAPI, setiap metode HTTP ini disebut sebuah "operasi".

Kita akan menyebut mereka juga "operasi".

Mendefinisikan dekorator operasi path¶

Python 3.8+

from readyapi import ReadyAPI

app = ReadyAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

@app.get("/") memberitahu ReadyAPI bahwa fungsi di bawahnya mengurusi request yang menuju ke:

path /
menggunakan operasi get

@decorator Info

Sintaksis @sesuatu di Python disebut "dekorator".

Dekorator ditempatkan di atas fungsi. Seperti sebuah topi cantik (Saya pikir istilah ini berasal dari situ).

"dekorator" memanggil dan bekerja dengan fungsi yang ada di bawahnya

Pada kondisi ini, dekorator ini memberi tahu ReadyAPI bahwa fungsi di bawah nya berhubungan dengan path / dengan operasi get.

Sehingga disebut dekorator operasi path.

Operasi lainnya yang bisa digunakan:

@app.post()
@app.put()
@app.delete()

Dan operasi unik lainnya:

@app.options()
@app.head()
@app.patch()
@app.trace()

Tips

Jika anda bisa menggunakan operasi apa saja (metode HTTP).

ReadyAPI tidak mengharuskan anda menggunakan operasi tertentu.

Informasi di sini hanyalah sebagai panduan, bukan keharusan.

Sebagai contoh, ketika menggunakan GraphQL, semua operasi umumnya hanya menggunakan POST.

Langkah 4: mendefinisikan fungsi operasi path¶

Ini "fungsi operasi path" kita:

path: adalah /.
operasi: adalah get.
fungsi: adalah fungsi yang ada di bawah dekorator (di bawah @app.get("/")).

Python 3.8+

from readyapi import ReadyAPI

app = ReadyAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

Ini adalah fungsi Python.

Fungsi ini dipanggil ReadyAPI setiap kali menerima request ke URL "/" dengan operasi GET.

Di kondisi ini, ini adalah sebuah fungsi async.

Anda bisa mendefinisikan fungsi ini sebagai fungsi normal daripada async def:

Python 3.8+

from readyapi import ReadyAPI

app = ReadyAPI()


@app.get("/")
def root():
    return {"message": "Hello World"}

Catatan

Jika anda tidak tahu perbedaannya, kunjungi Async: "Panduan cepat".

Langkah 5: hasilkan konten¶

Python 3.8+

from readyapi import ReadyAPI

app = ReadyAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

Anda bisa menghasilkan dict, list, nilai singular seperti str, int, dll.

Anda juga bisa menghasilkan model Pydantic (anda akan belajar mengenai ini nanti).

Ada banyak objek dan model yang secara otomatis dikonversi ke JSON (termasuk ORM, dll). Anda bisa menggunakan yang anda suka, kemungkinan sudah didukung.

Ringkasan¶

Impor ReadyAPI.
Buat sebuah instance app.
Tulis dekorator operasi path menggunakan dekorator seperti @app.get("/").
Definisikan fungsi operasi path; sebagai contoh, def root(): ....
Jalankan server development dengan perintah readyapi dev.

Langkah Pertama¶

Mencoba aplikasi¶

Dokumen API interaktif¶

Dokumen API alternatif¶

OpenAPI¶

"Schema"¶

"schema" API¶

"schema" Data¶

Schema OpenAPI and JSON¶

Lihat openapi.json¶

Kegunaan OpenAPI¶

Ringkasan, secara bertahap¶

Langkah 1: impor ReadyAPI¶

Langkah 2: buat "instance" dari ReadyAPI¶

Langkah 3: Buat operasi path¶

Path¶

Operasi¶

Mendefinisikan dekorator operasi path¶

Langkah 4: mendefinisikan fungsi operasi path¶

Langkah 5: hasilkan konten¶

Ringkasan¶

Lihat `openapi.json`¶

Langkah 1: impor `ReadyAPI`¶

Langkah 2: buat "instance" dari `ReadyAPI`¶