Merancang API RESTful dengan nested resource

pada



Merancang API RESTful dengan nested resource dan pertanyaan kompleks memerlukan pertimbangan teliti untuk memastikan ia adalah intuitif, efisien, dan mudah diselenggara. Berikut adalah beberapa amalan terbaik untuk mencapainya:

1. Gunakan URL Hierarki untuk Nested Resource

URL hierarki membantu untuk mentakrifkan hubungan antara sumber dengan jelas. Sebagai contoh, jika anda mempunyai pengguna dan pos, anda boleh gunakan:

  • /users/{userId}/posts: Mendapatkan pos untuk pengguna tertentu.
  • /users/{userId}/posts/{postId}: Mendapatkan pos tertentu untuk pengguna tertentu.

2. Kekalkan Konsistensi dalam Struktur URL

Konsistensi dalam pola URL menjadikan API lebih mudah diramal dan mudah digunakan. Kekalkan struktur yang jelas dan konsisten sepanjang API anda.

3. Gunakan Kaedah HTTP yang Sesuai

Gunakan kaedah HTTP standard untuk menunjukkan tindakan:

  • GET untuk mendapatkan sumber.
  • POST untuk mencipta sumber.
  • PUT/PATCH untuk mengemas kini sumber.
  • DELETE untuk memadam sumber.

4. Gunakan Parameter Pertanyaan untuk Penapisan, Pengisihan, dan Penomboran

Untuk pertanyaan kompleks, gunakan parameter pertanyaan untuk mengendalikan penapisan, pengisihan, dan penomboran. Ini memastikan URL bersih dan membolehkan pertanyaan yang fleksibel.

  • /posts?userId=1&sort=created_at&order=desc&page=2

5. Sahkan dan Bersihkan Input

Sentiasa sahkan dan bersihkan input untuk mencegah suntikan SQL dan kerentanan keselamatan lain. Gunakan kaedah pengesahan terbina dalam Laravel.

6. Laksanakan Pengendalian Ralat yang Betul

Kembalikan mesej ralat yang bermakna dan kod status HTTP yang sesuai. Sebagai contoh, kembalikan 404 Not Found jika sumber tidak ditemui dan 400 Bad Request untuk ralat pengesahan.

7. Gunakan Eloquent untuk Pertanyaan Kompleks

Manfaatkan keupayaan pertanyaan kuat Eloquent untuk pertanyaan kompleks. Gunakan hubungan, skop, dan kaedah pembina pertanyaan untuk membina pertanyaan kompleks.

8. Optimumkan untuk Prestasi

Pertimbangkan pengoptimuman prestasi seperti pemuatan eager untuk mengurangkan bilangan pertanyaan:

$users = User::with('posts.comments')->get();

9. Gunakan Kelas Sumber untuk Respons JSON

Gunakan kelas sumber Laravel untuk memformat respons JSON dengan konsisten:

return new UserResource($user);

10. Versi API Anda

Versi API anda untuk mengendalikan perubahan dengan lancar tanpa memecahkan klien yang sedia ada:

  • /v1/users/{userId}/posts
  • /v2/users/{userId}/posts

Contoh Takrifan Laluan Nested Resource dalam Laravel

use App\Http\Controllers\UserController;
use App\Http\Controllers\PostController;
use App\Http\Controllers\CommentController;

// Laluan Pengguna
Route::prefix('users')->group(function () {
    Route::get('/', [UserController::class, 'index']);
    Route::get('/{userId}', [UserController::class, 'show']);

    // Laluan Pos untuk Pengguna
    Route::prefix('{userId}/posts')->group(function () {
        Route::get('/', [PostController::class, 'indexByUser']);
        Route::get('/{postId}', [PostController::class, 'show']);

        // Laluan Komen untuk Pos
        Route::prefix('{postId}/comments')->group(function () {
            Route::get('/', [CommentController::class, 'indexByPost']);
            Route::get('/{commentId}', [CommentController::class, 'show']);
        });
    });
});

Contoh Eloquent untuk Pertanyaan Kompleks

Menggunakan Eloquent untuk mengendalikan pertanyaan kompleks dengan hubungan:

class PostController extends Controller
{
    public function indexByUser(Request $request, $userId)
    {
        $query = Post::where('user_id', $userId);

        // Terapkan penapisan
        if ($request->has('category')) {
            $query->where('category_id', $request->category);
        }

        // Terapkan pengisihan
        if ($request->has('sort')) {
            $sortOrder = $request->get('order', 'asc');
            $query->orderBy($request->sort, $sortOrder);
        }

        // Penomboran
        $posts = $query->paginate(10);

        return PostResource::collection($posts);
    }

    public function show($userId, $postId)
    {
        $post = Post::where('user_id', $userId)->findOrFail($postId);
        return new PostResource($post);
    }
}

Dengan mengikuti amalan terbaik ini, anda boleh merancang API RESTful yang kukuh, mudah digunakan, dan mudah diselenggara, walaupun dengan nested resource dan pertanyaan kompleks.

Ulasan

Catat Ulasan