Prinsip dan Praktik Terbaik Rancangan API
Pelajari cara merancang API RESTful yang bersih, konsisten, dan mudah dipelihara dengan berfokus pada arsitektur berorientasi sumber daya.
Prinsip dan Praktik Terbaik Rancangan API adalah pelajaran Elixir & Phoenix: Scalable Backend Development gratis di CoddyKit. Ini adalah pelajaran 1 dari 4. Kamu bisa membaca pelajaran lengkapnya di bawah secara gratis — lalu praktikkan langsung di browser dengan editor kode bawaan dan tutor AI 24/7. Ini adalah bagian dari jalur belajar Elixir & Phoenix: Scalable Backend Development, dan progresmu tersinkronisasi di web dan aplikasi CoddyKit. Kursus Elixir & Phoenix: Scalable Backend Development mencakup 4 pelajaran total.
Bagian dari pelajaran ini belum diterjemahkan dan ditampilkan dalam bahasa Inggris.
Welcome to API Design!
Welcome to the first lesson in our 'Building RESTful APIs with Phoenix' course! A well-designed API is crucial for building scalable and maintainable applications.
In this lesson, we'll dive into the fundamental principles and best practices for designing clean, consistent, and user-friendly RESTful APIs. Let's get started!
What is a RESTful API?
REST (Representational State Transfer) is an architectural style for networked applications. A RESTful API is one that adheres to these principles:
- Client-Server: Separation of concerns.
- Stateless: Each request from client to server must contain all information needed.
- Cacheable: Responses can be cached to improve performance.
- Layered System: Client cannot tell if it's connected directly to end server or an intermediary.
- Uniform Interface: The core of REST, simplifying interactions.
It's about interacting with resources using standard HTTP methods.
Resource-Oriented Thinking
At the heart of REST is the concept of a resource. Think of everything your API exposes as a resource. Resources are typically identified by unique URLs.
Instead of thinking about actions (like 'getProduct' or 'deleteUser'), think about the data itself (like 'product' or 'user').
For example, if you're building an e-commerce API, your resources might be:
- Products
- Orders
- Customers
- Categories
Each resource has a unique identifier and can have different representations (e.g., JSON, XML).
Crafting Consistent URLs
Your API's URLs (or endpoints) should be intuitive and predictable. Here are some best practices:
- Use plural nouns: For collections (e.g.,
/products, not/product). - Use nouns, not verbs: URLs should identify resources, not actions (e.g.,
/users, not/getAllUsers). - Be hierarchical: Show relationships (e.g.,
/users/123/orders). - Keep it simple: Avoid unnecessary complexity.
Consistency makes your API easier to understand and use.
HTTP Methods: The Verbs
HTTP methods (also called verbs) tell the server what action to perform on a resource. Mapping these correctly is key to RESTful design.
- GET: Retrieve data (safe, idempotent).
- POST: Create new data (not idempotent).
- PUT: Replace existing data (idempotent).
- PATCH: Partially update existing data (not idempotent).
- DELETE: Remove data (idempotent).
Idempotent means making the same request multiple times has the same effect as making it once (e.g., deleting a resource multiple times still results in it being deleted once).
Standard HTTP Status Codes
HTTP status codes communicate the result of an API request. Using them correctly is vital for clarity and debugging.
- 2xx Success:
200 OK,201 Created,204 No Content. - 4xx Client Error:
400 Bad Request,401 Unauthorized,403 Forbidden,404 Not Found,409 Conflict. - 5xx Server Error:
500 Internal Server Error,503 Service Unavailable.
Always return the most specific status code possible to help clients understand what happened.
API Data Formats: JSON
JSON (JavaScript Object Notation) is the de-facto standard for API request and response bodies due to its lightweight nature and readability.
Ensure your API consistently uses JSON for data exchange. Here's how a simple Elixir map might represent a JSON response for a product:
defmodule ProductAPI do
def get_product(id) do
# In a real API, this would fetch from a database
case id do
"prod_xyz" ->
%{
id: "prod_xyz",
name: "Wireless Headphones",
price: 99.99,
currency: "USD",
in_stock: true
}
_ ->
nil
end
end
end
IO.inspect(ProductAPI.get_product("prod_xyz"))Handling Query Parameters
Query parameters allow clients to filter, sort, and paginate resource collections. They appear after a ? in the URL (e.g., /products?category=electronics&sort=price).
Here's a simple Elixir function illustrating how a query string might be processed (in Phoenix, this is handled for you, but it shows the concept):
defmodule QueryParser do
def parse(query_string) do
query_string
|> String.split("&")
|> Enum.map(fn pair ->
[key, value] = String.split(pair, "=")
{String.to_atom(key), value}
end)
|> Enum.into(%{})
end
end
query_params = QueryParser.parse("category=books&sort=title&limit=10")
IO.inspect(query_params)API Versioning Strategies
As your API evolves, you'll need to introduce changes. Versioning prevents breaking existing client applications.
Common strategies include:
- URL Versioning: Include the version in the URL (e.g.,
/v1/products). Simple and clear, but changes the URL. - Header Versioning: Include the version in an HTTP header (e.g.,
Accept: application/vnd.myapi.v2+json). More flexible, but less visible.
Choose a strategy early and stick to it. URL versioning is often preferred for its simplicity.
Consistent Error Responses
When errors occur, your API should return clear, consistent error messages. This helps clients diagnose problems quickly.
A good error response typically includes:
- A clear error code or type.
- A human-readable message.
- Optional details (e.g., validation errors for specific fields).
Here's an example Elixir map for a structured error response:
defmodule ErrorFormatter do
def format_error(status, code, message, details \\ %{}) do
%{
status: status,
code: code,
message: message,
details: details
}
end
end
error_response = ErrorFormatter.format_error(
400,
"invalid_input",
"Validation failed",
%{email: "must be a valid email format"}
)
IO.inspect(error_response)Design Principle Challenge
Which of the following API endpoint designs best follows RESTful principles for retrieving a list of users?
Recap: Key Design Takeaways
Great job! You've covered the essential principles for designing robust and maintainable RESTful APIs.
- Think in resources (nouns, not verbs).
- Use consistent URLs with plural nouns.
- Map HTTP methods (GET, POST, PUT, PATCH, DELETE) correctly.
- Return appropriate HTTP status codes.
- Use JSON for request/response bodies.
- Implement query parameters for data manipulation.
- Plan for API versioning.
- Provide consistent error responses.
These principles will guide you in building APIs that are easy to understand, consume, and evolve. Next, we'll implement these designs in Phoenix!
Belajar Elixir dengan tutor AI — gratis
Tulis dan jalankan kode asli di browser kamu, dapatkan bantuan instan dari tutor AI 24/7, dan lanjutkan di mana kamu tinggalkan di web atau aplikasi.
- Kursus
- 12
- Pelajaran
- 48
Pertanyaan yang Sering Diajukan
Apakah pelajaran “Prinsip dan Praktik Terbaik Rancangan API” gratis?
Ya — teks lengkap “Prinsip dan Praktik Terbaik Rancangan API” gratis dibaca di sini di web. Untuk praktiknya secara interaktif (editor kode bawaan dan tutor AI 24/7) dan buka sisa kursus Elixir & Phoenix: Scalable Backend Development, upgrade ke CoddyKit PRO. Kursus Elixir & Phoenix: Scalable Backend Development mencakup 4 pelajaran total.
Apa yang akan aku pelajari di “Prinsip dan Praktik Terbaik Rancangan API”?
Pelajari cara merancang API RESTful yang bersih, konsisten, dan mudah dipelihara dengan berfokus pada arsitektur berorientasi sumber daya. Kamu berlatih Elixir & Phoenix: Scalable Backend Development dengan kode praktik yang langsung kamu jalankan di browser, dan tutor AI 24/7 menjawab pertanyaanmu saat kamu mengerjakan pelajaran ini.
Apakah aku perlu pengalaman untuk memulai Elixir & Phoenix: Scalable Backend Development?
Tidak diperlukan pengalaman sebelumnya. Elixir & Phoenix: Scalable Backend Development di CoddyKit dirancang untuk pemula hingga pelajar tingkat lanjut, jadi kamu bisa memulai di sini atau dari awal dan belajar sesuai kecepatan kamu sendiri. Ini adalah pelajaran 1 dari 4.
Berapa lama pelajaran “Prinsip dan Praktik Terbaik Rancangan API” memakan waktu?
Sebagian besar pelajaran CoddyKit memakan waktu sekitar 5–10 menit. Setiap pelajaran ringkas dan interaktif, jadi kamu membuat kemajuan stabil dan melanjutkan dari tempat kamu tinggalkan di web dan aplikasi.
Bisakah aku menulis dan menjalankan kode dalam pelajaran Elixir & Phoenix: Scalable Backend Development ini?
Ya. Setiap pelajaran Elixir & Phoenix: Scalable Backend Development menyertakan editor kode bawaan, jadi kamu menulis dan menjalankan kode nyata langsung di browser dan mendapatkan umpan balik AI instan — tidak diperlukan penyiapan lokal.
Semua pelajaran dalam kursus ini
- Prinsip dan Praktik Terbaik Rancangan API
- Menerapkan Titik Akhir API dan Serialisasi
- Strategi Autentikasi dan Otorisasi
- Paginasi, Pemfilteran & Pemberian Versi API