Có thể trình bày nguyên vẹn lí REST và cấu tạo tài liệu RESTful được nghe biết rộng thoải mái nhập giới xây dựng trang web trình bày công cộng và xây dựng phần mềm trình bày riêng rẽ.
Bạn đang xem: restful api là gì
Có thể nói bản thân thuộc REST ko cần là 1 loại technology. Nó là công thức tạo nên API với nguyên tắc tổ chức triển khai chắc chắn. Những nguyên tắc này nhằm mục đích chỉ dẫn xây dựng viên tạo nên môi trường thiên nhiên xử lý API request được trọn vẹn.
Để làm rõ rộng lớn về RESTful API tao tiếp tục lên đường theo thứ tự phân tích và lý giải những định nghĩa API, REST hoặc RESTful.
RESTful API là 1 chi phí chuẩn chỉnh sử dụng trong những việc design API cho những phần mềm trang web (thiết tiếp Web services) nhằm tiện mang lại việc vận hành những resource. Nó chú ý nhập khoáng sản khối hệ thống (tệp văn phiên bản, hình ảnh, tiếng động, video clip, hoặc tài liệu động…), bao hàm những hiện trạng khoáng sản được format và được truyền đạt qua chuyện HTTP.
Xem thêm: những địa điểm tuyển chọn dụng xây dựng API thú vị bên trên Topdev
Diễn giải những trở nên phần
API (Application Programming Interface) là 1 luyện những quy tắc và chế độ tuy nhiên Từ đó, một phần mềm hay như là một bộ phận tiếp tục tương tác với cùng một phần mềm hoặc bộ phận không giống. API hoàn toàn có thể trả về tài liệu tuy nhiên bạn phải mang lại phần mềm của tớ ở những loại tài liệu phổ cập như JSON hoặc XML.
REST (REpresentational State Transfer) là 1 dạng quy đổi cấu tạo tài liệu, một loại phong cách thiết kế nhằm viết lách API. Nó dùng công thức HTTP đơn giản và giản dị muốn tạo mang lại tiếp xúc trong những máy. Vì vậy, chứ không dùng một URL mang lại việc xử lý một số trong những vấn đề người tiêu dùng, REST gửi một đòi hỏi HTTP như GET, POST, DELETE, vv cho tới một URL nhằm xử lý tài liệu.
RESTful API là 1 chi phí chuẩn chỉnh sử dụng trong những việc design những API cho những phần mềm trang web nhằm vận hành những resource. RESTful là 1 trong mỗi loại design API được dùng phổ cập thời buổi này làm cho những phần mềm (web, mobile…) không giống nhau tiếp xúc cùng nhau.
Chức năng cần thiết nhất của REST là quy ấn định cơ hội dùng những HTTP method (như GET, POST, PUT, DELETE…) và cơ hội format những URL mang lại phần mềm trang web nhằm cai quản những resource. RESTful ko quy ấn định logic code phần mềm và giới hạn max bởi vì ngôn từ xây dựng phần mềm, ngẫu nhiên ngôn từ hoặc framework nào thì cũng hoàn toàn có thể dùng nhằm design một RESTful API.
RESTful hoạt động và sinh hoạt như vậy nào?
REST hoạt động và sinh hoạt đa số phụ thuộc gửi gắm thức HTTP. Các hoạt động và sinh hoạt cơ phiên bản nêu bên trên tiếp tục dùng những công thức HTTP riêng rẽ.
- GET (SELECT): Trả về một Resource hoặc một list Resource.
- POST (CREATE): Tạo mới mẻ một Resource.
- PUT (UPDATE): Cập nhật vấn đề mang lại Resource.
- DELETE (DELETE): Xoá một Resource.
Những công thức hoặc hoạt động và sinh hoạt này thông thường được gọi là CRUD ứng với Create, Read, Update, Delete – Tạo, Đọc, Sửa, Xóa.
Hiện bên trên phần đông xây dựng viên viết lách RESTful API giờ trên đây đều lựa chọn JSON là format đầu tiên tuy nhiên cũng đều có nhiều người lựa chọn XML thực hiện format, trình bày công cộng sử dụng thế nào là cũng rất được miễn tiện và nhanh chóng.
Authentication và tài liệu trả về
RESTful API ko dùng session và cookie, nó dùng một access_token với từng request. Dữ liệu trả về thông thường với cấu tạo như sau:
{ "data" : { "id": "1", "name": "TopDev" } }
Status code
Khi tất cả chúng ta request một API nào là này thường thì sẽ có được vài ba status code nhằm nhận thấy sau:
- 200 OK – Trả về thành công xuất sắc mang lại những công thức GET, PUT, PATCH hoặc DELETE.
- 201 Created – Trả về Khi một Resouce vừa mới được tạo nên thành công xuất sắc.
- 204 No Content – Trả về Khi Resource xoá thành công xuất sắc.
- 304 Not Modified – Client hoàn toàn có thể dùng tài liệu cache.
- 400 Bad Request – Request không khớp lệ
- 401 Unauthorized – Request cần phải có auth.
- 403 Forbidden – bị kể từ chối ko được cho phép.
- 404 Not Found – Không nhìn thấy resource kể từ URI
- 405 Method Not Allowed – Phương thức ko được cho phép với user thời điểm hiện tại.
- 410 Gone – Resource không hề tồn bên trên, Version cũ đang được không hề tương hỗ.
- 415 Unsupported Media Type – Không tương hỗ loại Resource này.
- 422 Unprocessable Entity – Dữ liệu ko được xác thực
- 429 Too Many Requests – Request bị kể từ chối tự bị giới hạn
Nên dùng Version
Luôn dùng version nhằm khi chúng ta cần thiết tăng cấp API vẫn tương hỗ những API cũ.
Xây dựng API với Laravel
Lấy việc thi công api bên trên Laravel nhằm thực hiện ví dụ, trước lúc lên đường nhập tao tổng quan liêu về Http Request.
HTTP Request
HTTP request với toàn bộ 9 loại method , 2 loại được dùng phổ cập nhất là GET và POST
- GET: được dùng nhằm lấy vấn đề kể từ server theo đòi URI đang được cung ứng.
- HEAD: giống như với GET tuy nhiên response trả về không tồn tại body toàn thân, chỉ mất header.
- POST: gửi vấn đề cho tới máy chủ trải qua những biểu hình mẫu http.
- PUT: ghi đè toàn bộ vấn đề của đối tượng người dùng với những gì được trình lên.
- PATCH: ghi đè những vấn đề được thay cho thay đổi của đối tượng người dùng.
- DELETE: xóa khoáng sản bên trên server.
- CONNECT: thiết lập một liên kết cho tới server theo đòi URI.
- OPTIONS: tế bào miêu tả những tùy lựa chọn tiếp xúc mang lại resource.
- TRACE: triển khai một bài bác test loop – back theo đòi lối kéo đến resource.
RESTful Route
Viết Api thì tiếp tục khai báo router nhập tệp tin routes/api.php chứ không dùng tệp tin routes/web.php. Các setting đem mang lại tệp tin api.php nhập laravel:
- Url: những route được khai báo nhập tệp tin này đem ấn định với prefix url là api (ví dụ:
happyxoang.com/api/products) - Middleware: đem ấn định sẽ tiến hành gán Middleware Group là api, nhập tệp tin
app/Http/Kerneltiếp tục thấy 2 middleware nằm trong Middleware Group: api là throttle (giới hạn request / time) và bindings (model binding).
Có thể tùy chỉnh độ quý hiếm đem ấn định này nhập method mapApiRoutes nhập tệp tin app/Providers/RouteServiceProvider.php
Tạo những route nhằm triển khai những thao tác như CRUD (Create, Read, Update, Delete):
// Lấy list sản phẩm Route::get('products', 'ApiProductController@index')->name('products.index'); // Lấy detail thành phầm theo đòi id Route::get('products/{id}', 'ApiProductController@show')->name('products.show'); // Add sản phẩm Route::post('products', 'ApiProductController@store')->name('products.store'); // Update info thành phầm theo đòi id # Sử dụng put nếu như update toàn cỗ những field Route::put('products/{id}', 'ApiProductController@update')->name('products.update'); # Sử dụng patch nếu như update 1 vài ba field Route::patch('products/{id}', 'ApiProductController@update')->name('products.update'); // Xóa thành phầm theo đòi id Route::delete('products/{id}', 'ApiProductController@destroy')->name('products.destroy');
Mặc ấn định route và được gán middleware bindings, nếu còn muốn dùng model binding nhập controller thì tất cả chúng ta sửa lại thông số nhập route như sau:
Route::get('products/{product}', 'ApiProductController@show')->name('products.show'); Route::put('products/{product}', 'ApiProductController@update')->name('products.update'); Route::patch('products/{product}', 'ApiProductController@update')->name('products.update'); Route::delete('products/{product}', 'ApiProductController@destroy')->name('products.destroy');
Ngoài đi ra nhập laravel cũng tương hỗ tất cả chúng ta một cách khai báo cộc gọn gàng hơn:
//Nếu không thích dùng toàn cỗ method nhập apiResource quý khách hoàn toàn có thể hướng dẫn và chỉ định dùng 1 vài ba method bởi vì hàm only Route::apiResource('products', 'ApiProductController')->only(['index', 'show']); //Hoặc nếu còn muốn vô hiệu hóa lên đường một số method ko sử dụng thì hoàn toàn có thể dùng hàm except Route::apiResource('products', 'ApiProductController')->except(['show', 'update']);
Resource Controllers
Tương ứng với các Route RESTful đang được khai báo phía trên, quan trọng đặc biệt nếu như sử dụng method apiResource thì laravel cũng tương hỗ những method xử lí ứng nhập controller.
Xem thêm: lá trầu không có tác dụng gì
Để đưa đến Resource Controllers tất cả chúng ta chạy mệnh lệnh sau
php artisan make:controller Api/ProductController -api
File ProductController đưa đến tiếp tục như sau<?php namespace AppHttpControllersApi; use IlluminateHttpRequest; use AppHttpControllersController; class ProductController extends Controller { /** * Display a listing of the resource. * * @return IlluminateHttpResponse */ public function index() { // } /** * Store a newly created resource in storage. * * @param IlluminateHttpRequest $request * @return IlluminateHttpResponse */ public function store(Request $request) { // } /** * Display the specified resource. * * @param int $id * @return IlluminateHttpResponse */ public function show($id) { // } /** * Update the specified resource in storage. * * @param IlluminateHttpRequest $request * @param int $id * @return IlluminateHttpResponse */ public function update(Request $request, $id) { // } /** * Remove the specified resource from storage. * * @param int $id * @return IlluminateHttpResponse */ public function destroy($id) { // } }
Ngoài đi ra nếu còn muốn dùng model binding Khi tạo nên Resource Controllers thì sử dụng mệnh lệnh mặt mày dưới
php artisan make:controller Api/ProductController --api --model=Models/Product
File ProductController đưa đến tiếp tục như sau, tất cả chúng ta nhằm ý thông số của những method show, update, destroy tiếp tục thay cho thay đổi 1 chút.
<?php namespace AppHttpControllersApi; use AppModelsProduct; use IlluminateHttpRequest; use AppHttpControllersController; class ProductController extends Controller { /** * Display a listing of the resource. * * @return IlluminateHttpResponse */ public function index() { // } /** * Store a newly created resource in storage. * * @param IlluminateHttpRequest $request * @return IlluminateHttpResponse */ public function store(Request $request) { // } /** * Display the specified resource. * * @param AppModelsProduct $product * @return IlluminateHttpResponse */ public function show(Product $product) { // } /** * Update the specified resource in storage. * * @param IlluminateHttpRequest $request * @param AppModelsProduct $product * @return IlluminateHttpResponse */ public function update(Request $request, Product $product) { // } /** * Remove the specified resource from storage. * * @param AppModelsProduct $product * @return IlluminateHttpResponse */ public function destroy(Product $product) { // } }
Demo 1 đoạn code đơn giản và giản dị nhập controller kết phù hợp với model binding và route apiResource Khi thi công API:
<?php namespace AppHttpControllersApi; use AppHttpControllersController; use AppModelsProduct; use IlluminateHttpRequest; class ProductController extends Controller { /** * Display a listing of the resource. * * @return Product[]|IlluminateDatabaseEloquentCollection */ public function index() { return Product::all(); } /** * Store a newly created resource in storage. * * @param Request $request * @return Product|IlluminateDatabaseEloquentModel */ public function store(Request $request) { return Product::create($request->all()); } /** * Display the specified resource. * * @param Product $product * @return Product */ public function show(Product $product) { return $product; } /** * Update the specified resource in storage. * * @param Request $request * @param Product $product * @return bool */ public function update(Request $request, Product $product) { return $product->update($request->all()); } /** * Remove the specified resource from storage. * * @param Product $product * @throws Exception */ public function destroy(Product $product) { $product->delete(); } }
Mặc ấn định Khi dùng route apiResource thì tài liệu trả về tiếp tục tự động hóa được đem quý phái loại JSON và sẽ có được status ứng nên chỉ việc return tài liệu đi ra là được.
Còn nếu còn muốn tùy biến hóa status trả về thì hoàn toàn có thể tìm hiểu thêm cơ hội phía bên dưới với dùng class IlluminateHttpResponse nhằm lấy status chứ không fix độ quý hiếm nhập ví như HTTP_OK ứng được xem là 200
<?php namespace AppHttpControllers; use AppModelsProduct; use IlluminateHttpRequest; use IlluminateHttpResponse; class ProductController extends Controller { /** * Display a listing of the resource. * * @return IlluminateHttpJsonResponse */ public function index() { $products = Product::all(); return response()->json($products, Response::HTTP_OK); } } Eloquent Resources
Khi thi công API, bạn cũng có thể cần thiết transform tài liệu kể từ controller trước lúc trả về cho tất cả những người sử dụng phần mềm của doanh nghiệp, laravel đã và đang tương hỗ điều này với Eloquent Resources
Để đưa đến 1 class quy đổi tất cả chúng ta chạy mệnh lệnh sau
php artisan make:resource Product
File app/Http/Resources/Product.php sẽ có được nội dung như sau
<?php
namespace AppHttpResources;
use IlluminateHttpResourcesJsonJsonResource;
class Product extends JsonResource
{
/**
* Transform the resource into an array.
*
* @param IlluminateHttpRequest $request
* @return array
*/
public function toArray($request)
{
return parent::toArray($request);
}
}
Mình tiếp tục tùy chỉnh tài liệu trả về là chỉ mất title và price
<?php namespace AppHttpResources; use IlluminateHttpResourcesJsonJsonResource; class Product extends JsonResource{ /** * Transform the resource into an array. * * @param IlluminateHttpRequest $request * @return array */ public function toArray($request){ return [ 'title' => $this->title, 'price' => $this->price, ]; } }
Ở controller thì bản thân tiếp tục sửa lại như sau
<?php namespace AppHttpControllersApi; use AppHttpControllersController; use AppModelsProduct; use IlluminateHttpRequest; use AppHttpResourcesProduct as ProductResource; class ProductController extends Controller{ /** * Display a listing of the resource. * * @return Product[]|IlluminateDatabaseEloquentCollection */ public function index(){ $products = Product::all(); return ProductResource::collection($products); } /** * Store a newly created resource in storage. * * @param Request $request * @return Product|IlluminateDatabaseEloquentModel */ public function store(Request $request){ $product = Product::create($request->all()); return new ProductResource($product); } /** * Display the specified resource. * * @param Product $product * @return Product */ public function show(Product $product){ return new ProductResource($product); } /** * Update the specified resource in storage. * * @param Request $request * @param Product $product * @return bool */ public function update(Request $request, Product $product){ return $product->update($request->all()); } /** * Remove the specified resource from storage. * * @param Product $product * @throws Exception */ public function destroy(Product $product){ $product->delete(); } }
Ngoài số lượng giới hạn tài liệu trả về như title hoặc price, laravel cũng tương hỗ thật nhiều loại như tăng relationships, data …, quý khách hoàn toàn có thể hướng dẫn thêm docs bên trên Laravel.
Authorization
Hiện bên trên với 3 chế độ Authorize chính:
- HTTP Basic
- JSON Web Token (JWT)
- OAuth2
Tùy nằm trong nhập service của doanh nghiệp, tuy nhiên nên chọn loại Authorize với cường độ thích hợp, nỗ lực lưu giữ nó càng đơn giản và giản dị càng đảm bảo chất lượng.
CORS Policy
Viết API thì cũng cần được xem xét về CORS là gì?
API Document
Ai cũng biết việc viết lách API docs là quan trọng, song để sở hữu một API docs hoàn hảo cũng tiêu hao tương đối nhiều thời hạn. Nhất là trong những khi dự án công trình lập cập thì quý khách thông thường chỉ nhằm API docs ở tại mức siêu cơ phiên bản. Tham khảo tăng cơ hội viết lách API Document.
API document là 1 phần tương tự động như Unit Test vậy – lấy cộc nhằm nuôi lâu năm.
Nếu ko được che chở kỹ, thì đến thời điểm maintain hoặc thay cho thay đổi spec thì kết quả tiếp tục đặc biệt thảm khốc, bên dưới đó là một số trong những chú ý khi viết lách docs:
- Mô miêu tả không thiếu về params request: bao gồm những params nào là, datatype, require hoặc optional.
- Nên thể hiện những ví dụ về HTTP requests và responses với data chuẩn chỉnh.
- Cập nhật Docs thông thường xuyên, nhằm sát nhất với API với bất kể thay cho thay đổi gì.
- Format, cú pháp rất cần phải nhất quán, tế bào miêu tả rõ nét, đúng mực.
Tham khảo tăng những việc thực hiện API bổng cao thú vị bên trên đây
Xem thêm: apart from là gì
Bình luận