Membangun API RESTful adalah keterampilan mendasar untuk pengembangan web modern, memungkinkan komunikasi yang lancar antara klien dan server. Flask-RESTX, sebuah ekstensi dari framework Flask yang populer, menyederhanakan proses ini dengan menyediakan alat untuk membuat API yang kuat secara efisien. Dalam tutorial ini, kita akan menjelajahi cara membangun API RESTful menggunakan Flask-RESTX dan mendemonstrasikan cara mengujinya dengan Apidog, sebuah platform terintegrasi untuk desain API, debugging, dokumentasi, mocking, dan pengujian.
1. Pengantar API RESTful
REST (Representational State Transfer) adalah gaya arsitektur yang menggunakan metode HTTP standar untuk berinteraksi dengan sumber daya. API yang mematuhi prinsip REST disebut API RESTful. Mereka menyediakan antarmuka yang dapat diprediksi dan seragam untuk interaksi klien-server, membuat layanan web lebih mudah diakses dan dipelihara.
2. Menyiapkan Lingkungan Pengembangan Anda
Sebelum kita mulai membangun API kita, mari kita siapkan lingkungan pengembangan kita.
Prasyarat
Python 3.7 atau lebih tinggi: Pastikan Python terinstal di sistem Anda. Verifikasi dengan menjalankan:
python --version
Lingkungan Virtual: Merupakan praktik yang baik untuk membuat lingkungan virtual untuk proyek Anda untuk mengelola dependensi.
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
Menginstal Flask dan Flask-RESTX
Dengan lingkungan virtual diaktifkan, instal Flask dan Flask-RESTX menggunakan pip:
pip install flask flask-restx
Perintah ini menginstal Flask dan Flask-RESTX, memungkinkan kita untuk membangun dan mengelola titik akhir API kita secara efektif.
3. Menginstal dan Mengonfigurasi Flask-RESTX
Flask-RESTX adalah ekstensi yang menambahkan dukungan untuk membangun API REST dengan cepat menggunakan Flask. Ini mendorong praktik terbaik dengan pengaturan minimal.
Instalasi
Jika Anda belum menginstal Flask-RESTX, Anda dapat melakukannya menggunakan pip:
pip install flask-restx
Konfigurasi
Buat file Python baru, misalnya, app.py, dan siapkan konfigurasi dasar:
from flask import Flask
from flask_restx import Api
app = Flask(__name__)
api = Api(app, version='1.0', title='Sample API',
description='A sample API using Flask-RESTX')
if __name__ == '__main__':
app.run(debug=True)
Skrip ini menginisialisasi aplikasi Flask dan membungkusnya dengan instance API Flask-RESTX, menyediakan fondasi untuk membangun titik akhir.
4. Membuat Titik Akhir API Pertama Anda
Mari kita buat titik akhir sederhana untuk memahami cara kerja Flask-RESTX.
Mendefinisikan Namespace
Namespace di Flask-RESTX membantu mengatur API Anda dan mencegah tabrakan nama titik akhir.
from flask_restx import Namespace, Resource
ns = Namespace('hello', description='Hello World operations')
Membuat Sumber Daya
Sumber daya di Flask-RESTX sesuai dengan titik akhir dan menentukan bagaimana metode HTTP ditangani.
@ns.route('/')
class HelloWorld(Resource):
def get(self):
return {'message': 'Hello, World!'}
Mendaftarkan Namespace
Terakhir, daftarkan namespace dengan API:
api.add_namespace(ns)
Sekarang, ketika Anda menjalankan aplikasi Anda dan menavigasi ke http://localhost:5000/hello/, Anda akan melihat:
{
"message": "Hello, World!"
}
5. Menstrukturkan Aplikasi Flask-RESTX Anda
Seiring pertumbuhan aplikasi Anda, penting untuk menjaga struktur yang bersih dan terorganisir.
Tata Letak Proyek yang Direkomendasikan
project/
├── app/
│ ├── __init__.py
│ ├── controllers/
│ │ ├── __init__.py
│ │ └── hello_controller.py
│ ├── models/
│ │ ├── __init__.py
│ │ └── hello_model.py
│ └── services/
│ ├── __init__.py
│ └── hello_service.py
├── run.py
└── requirements.txt
Menginisialisasi Aplikasi
Di app/__init__.py:
from flask import Flask
from flask_restx import Api
def create_app():
app = Flask(__name__)
api = Api(app, version='1.0', title='Sample API',
description='A sample API using Flask-RESTX')
from .controllers.hello_controller import ns as hello_namespace
api.add_namespace(hello_namespace)
return app
Di run.py:
from app import create_app
app = create_app()
if __name__ == '__main__':
app.run(debug=True)
Pendekatan modular ini memisahkan kekhawatiran, membuat aplikasi lebih mudah dipelihara dan diskalakan.
6. Mengimplementasikan Operasi CRUD
Operasi CRUD—Create, Read, Update, Delete—adalah fundamental untuk pengembangan API. Mari kita implementasikan ini untuk sumber daya Item sederhana.
Mendefinisikan Model
Di app/models/item_model.py:
from flask_restx import fields
def get_item_model(api):
return api.model('Item', {
'id': fields.Integer(readOnly=True, description='The unique identifier of an item'),
'name': fields.String(required=True, description='Item name'),
'price': fields.Float(required=True, description='Item price')
})
Mengimplementasikan Sumber Daya
Di app/controllers/item_controller.py:
from flask_restx import Namespace, Resource, reqparse
from app.models.item_model import get_item_model
ns = Namespace('items', description='Item operations')
item_model = get_item_model(ns)
items = []
item_id_counter = 1
parser = reqparse.RequestParser()
parser.add_argument('name', type=str, required=True, help='Name of the item')
parser.add_argument('price', type=float, required=True, help='Price of the item')
@ns.route('/')
class ItemList(Resource):
@ns.marshal_list_with(item_model)
def get(self):
return items
@ns.expect(item_model)
@ns.marshal_with(item_model, code=201)
def post(self):
global item_id_counter
args = parser.parse_args()
item = {
'id': item_id_counter,
'name': args['name'],
'price': args['price']
}
items.append(item)
item_id_counter += 1
return item, 201
@ns.route('/<int:id>')
@ns.response(404, 'Item not found')
@ns.param('id', 'The item identifier')
class Item(Resource):
@ns.marshal_with(item_model)
def get(self, id):
item = next((item for item in items if item['id'] == id), None)
if item is not None:
return item
ns.abort(404, message="Item not found")
@ns.expect(item_model)
@ns.marshal_with(item_model)
def put(self, id):
item = next((item for item in items if item['id'] == id), None)
if item is not None:
args = parser.parse_args()
item.update({
'name': args['name'],
'price': args['price']
})
return item
ns.abort(404, message="Item not found")
@ns.response(204, 'Item deleted')
def delete(self, id):
global items
item = next((item for item in items if item['id'] == id), None)
if item is not None:
items = [item for item in items if item['id'] != id]
return '', 204
ns.abort(404, message="Item not found")
Dalam implementasi ini:
- GET /items/: Mengambil daftar item.
- POST /items/: Menambahkan item baru.
- GET /items/{id}: Mengambil item tertentu berdasarkan ID.
- PUT /items/{id}: Memperbarui item yang ada berdasarkan ID.
- DELETE /items/{id}: Menghapus item berdasarkan ID.
Pengaturan ini menyediakan antarmuka CRUD lengkap untuk mengelola item di API Anda.
7. Memvalidasi dan Menserialisasikan Data dengan Flask-RESTX
Validasi dan serialisasi data sangat penting untuk memastikan integritas dan konsistensi data yang diproses API Anda. Flask-RESTX menawarkan dekorator dan bidang untuk memfasilitasi ini.
Menggunakan Model untuk Validasi
Definisikan model untuk menentukan format input dan output yang diharapkan.
from flask_restx import fields
item_model = api.model('Item', {
'id': fields.Integer(readOnly=True, description='The unique identifier of an item'),
'name': fields.String(required=True, description='Item name'),
'price': fields.Float(required=True, description='Item price')
})
Dengan mendekorasi metode sumber daya Anda dengan @ns.expect(item_model), Flask-RESTX akan secara otomatis memvalidasi data JSON yang masuk terhadap model ini.
Menserialisasikan Respons
Gunakan dekorator @ns.marshal_with untuk memformat output sesuai dengan model.
@ns.marshal_with(item_model)
def get(self, id):
# Retrieve and return the item
Ini memastikan bahwa data respons mematuhi struktur yang ditentukan, mempromosikan konsistensi di seluruh API Anda.
8. Menguji API RESTful dengan Apidog
Pengujian adalah bagian penting dari pengembangan API, memastikan bahwa titik akhir Anda berfungsi seperti yang diharapkan. Apidog adalah alat komprehensif yang menyederhanakan pengujian, desain, dan dokumentasi API.
Menyiapkan Apidog
Unduh dan Instal: Unduh Apidog secara gratis dan ikuti instruksi instalasi untuk sistem operasi Anda.
Buat Proyek Baru: Luncurkan Apidog dan buat proyek baru untuk API Anda.
Mengimpor Spesifikasi API Anda
Jika Anda telah mendokumentasikan API Anda menggunakan OpenAPI/Swagger, Anda dapat mengimpor spesifikasi ke Apidog:
Impor Spesifikasi: Di proyek Apidog Anda, pilih opsi untuk mengimpor spesifikasi API dan unggah file OpenAPI Anda.
Jelajahi Titik Akhir: Apidog akan mengurai file dan menampilkan titik akhir, parameter, dan model API Anda.
Anda juga dapat mendesain API dari awal di Apidog.
Menguji Titik Akhir
Pilih Titik Akhir: Pilih titik akhir yang ingin Anda uji dari daftar.
Konfigurasikan Permintaan:
- Metode: Pastikan metode HTTP yang benar (GET, POST, PUT, DELETE) dipilih.
- Parameter: Masukkan parameter kueri atau variabel jalur yang diperlukan.
- Header: Atur header yang diperlukan, seperti
Content-Type: application/json. - Body: Untuk permintaan POST dan PUT, berikan payload JSON.
Kirim Permintaan: Klik tombol Send untuk mengeksekusi permintaan.
Tinjau Respons:
(Tip pro: Apidog memvalidasi respons API secara otomatis.)
- Kode Status: Verifikasi bahwa kode status respons sesuai dengan harapan (misalnya, 200 untuk keberhasilan, 201 untuk pembuatan).
- Body Respons: Periksa apakah data yang dikembalikan benar dan diformat dengan benar.
- Header: Periksa header respons untuk informasi tambahan.
9. Menghasilkan Dokumentasi API dengan Flask-RESTX
Dokumentasi yang komprehensif sangat penting untuk setiap API, memfasilitasi kemudahan penggunaan dan integrasi bagi pengembang. Flask-RESTX menyediakan dukungan bawaan untuk menghasilkan dokumentasi API interaktif.
Menghasilkan dokumentasi API yang komprehensif dan ramah pengguna sangat penting bagi pengembang dan pengguna yang berinteraksi dengan API Anda. Flask-RESTX menyederhanakan proses ini dengan secara otomatis menghasilkan dokumentasi Swagger UI, menyediakan antarmuka interaktif untuk menjelajahi dan menguji titik akhir API Anda.
Dokumentasi Swagger Otomatis
Secara default, Flask-RESTX menghasilkan dokumentasi Swagger yang dapat diakses di URL root API Anda. Fitur ini menawarkan ikhtisar langsung dari struktur API Anda dan titik akhir yang tersedia tanpa konfigurasi tambahan.
Menyesuaikan Dokumentasi dengan Dekorator
Flask-RESTX menyediakan beberapa dekorator untuk meningkatkan dan menyesuaikan dokumentasi API Anda:
@api.doc(): Menambahkan informasi tambahan ke sumber daya atau metode Anda. Misalnya, untuk mendokumentasikan parameter:
@api.route('/my-resource/<id>')
@api.doc(params={'id': 'An ID'})
class MyResource(Resource):
def get(self, id):
return {}
@api.response(): Mendokumentasikan respons yang diharapkan, termasuk kode status dan deskripsi:
@api.route('/my-resource/<id>')
class MyResource(Resource):
@api.response(403, 'Not Authorized')
def post(self, id):
api.abort(403)
@api.marshal_with(): Menentukan model output untuk respons, memastikan pemformatan data yang konsisten:
@api.route('/item/<int:id>')
class ItemResource(Resource):
@api.marshal_with(item_model)
def get(self, id):
# Retrieve and return the item
@api.expect(): Mendefinisikan model input yang diharapkan untuk permintaan, memfasilitasi validasi dan dokumentasi:
@api.route('/item')
class ItemResource(Resource):
@api.expect(item_model)
def post(self):
# Handle the post request
Mengatur dengan Namespace
Namespace di Flask-RESTX membantu mengelompokkan sumber daya terkait, meningkatkan organisasi API Anda dan dokumentasinya.
from flask_restx import Namespace, Resource
ns = Namespace('items', description='Item operations')
@ns.route('/<int:id>')
class ItemResource(Resource):
def get(self, id):
# Retrieve and return the item
Dengan mendaftarkan namespace dengan API, semua rute dan dokumentasi terkait dikelompokkan dengan tepat:
api.add_namespace(ns)
Mengakses Swagger UI
Setelah aplikasi Flask-RESTX Anda berjalan, Anda dapat mengakses Swagger UI yang dihasilkan secara otomatis dengan menavigasi ke URL root API Anda (misalnya, http://localhost:5000/). Antarmuka ini menyediakan eksplorasi interaktif dari API Anda, menampilkan titik akhir yang tersedia, input yang diharapkan, dan respons potensial.
Dengan memanfaatkan fitur-fitur ini, Anda memastikan bahwa API Anda terdokumentasi dengan baik, ramah pengguna, dan mudah dipahami oleh pengembang dan konsumen.
10. Meningkatkan Dokumentasi API dengan Apidog
Meskipun Flask-RESTX menyediakan dokumentasi dasar, Apidog menawarkan fitur lanjutan untuk dokumentasi API, termasuk penyesuaian, pembuatan kode otomatis, dan pengujian waktu nyata.
Gunakan editor visual Apidog untuk menentukan titik akhir API Anda, parameter permintaan, dan skema respons. Dengan satu klik, hasilkan dokumentasi API yang komprehensif dan interaktif.
Bagikan dokumentasi Anda dengan anggota tim atau mitra eksternal, memungkinkan mereka untuk menguji titik akhir API langsung di dalam dokumentasi.
Dengan mengintegrasikan Flask-RESTX dengan Apidog, Anda dapat membuat API yang kuat dengan dokumentasi tingkat profesional, meningkatkan efisiensi pengembangan dan pengalaman pengguna.
Kesimpulan
Dalam panduan komprehensif ini, kita telah menjelajahi proses membangun API RESTful menggunakan Flask-RESTX, sebuah ekstensi yang kuat untuk Flask yang menyederhanakan pengembangan API. Kita telah membahas topik-topik penting seperti menyiapkan lingkungan pengembangan Anda, membuat dan mengelola titik akhir API, memvalidasi dan menserialisasikan data, dan menghasilkan dokumentasi API interaktif.
Selain itu, kita telah memperkenalkan Apidog, alat serbaguna yang meningkatkan alur kerja pengembangan API Anda dengan menawarkan fitur-fitur seperti pengujian otomatis, pengujian kinerja, dan dokumentasi kolaboratif. Dengan mengintegrasikan Apidog ke dalam proses pengembangan Anda, Anda dapat memastikan bahwa API Anda kuat, efisien, dan terdokumentasi dengan baik.
