Có thể phát biểu vẹn toàn lí REST và cấu hình tài liệu RESTful được nghe biết rộng thoải mái nhập giới thiết kế trang web phát biểu công cộng và thiết kế phần mềm phát biểu riêng biệt.
Bạn đang xem: rest api là gì
Có thể nói bản thân thiết REST ko cần là một trong những 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 thiết kế 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 tớ 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à một trong những xài chuẩn chỉnh người sử dụng trong công việc kiến thiết 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 quản lý và 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, đoạn Clip, hoặc tài liệu động…), bao hàm những hiện trạng khoáng sản được định hình và được truyền đạt qua quýt HTTP.
Xem thêm: những địa điểm tuyển chọn dụng thiết kế API thú vị bên trên Topdev
Diễn giải những trở nên phần
API (Application Programming Interface) là một trong những tập dượt những quy tắc và chế độ nhưng mà Từ đó, một phần mềm hay là 1 bộ phận tiếp tục tương tác với cùng 1 phần mềm hoặc bộ phận không giống. API rất có thể trả về tài liệu nhưng mà 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à một trong những dạng quy đổi cấu hình tài liệu, một loại phong cách thiết kế nhằm ghi chép API. Nó dùng công thức HTTP giản dị và đơn giản sẽ tạo mang lại tiếp xúc trong số 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à một trong những xài chuẩn chỉnh người sử dụng trong công việc kiến thiết những API cho những phần mềm trang web nhằm quản lý và vận hành những resource. RESTful là một trong những trong mỗi loại kiến thiết API được dùng phổ cập thời buổi này khiến 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 định hình 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 ngôn từ thiết kế phần mềm, ngẫu nhiên ngôn từ hoặc framework nào thì cũng rất có thể dùng nhằm kiến thiết 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ố nhờ vào phú 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 biệt.
- GET (SELECT): Trả về một Resource hoặc một list Resource.
- POST (CREATE): Tạo mới nhất 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 số đông thiết kế viên ghi chép RESTful API giờ trên đây đều lựa chọn JSON là format đầu tiên tuy nhiên cũng có thể có nhiều người lựa chọn XML thực hiện format, phát biểu công cộng người sử dụng thế này cũng rất được miễn tiện và thời gian nhanh.
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 sở hữu cấu hình như sau:
{ "data" : { "id": "1", "name": "TopDev" } }
Status code
Khi tất cả chúng ta request một API này 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 rất 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 chấp nhận.
- 404 Not Found – Không nhìn thấy resource kể từ URI
- 405 Method Not Allowed – Phương thức ko được chấp nhận với user lúc này.
- 410 Gone – Resource không hề tồn bên trên, Version cũ vẫn 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 bởi 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 upgrade API nhưng mà vẫn tương hỗ những API cũ.
Xây dựng API với Laravel
Lấy việc thiết kế api bên trên Laravel nhằm thực hiện ví dụ, trước lúc lên đường nhập tớ tổng quan liêu về Http Request.
HTTP Request
HTTP request sở hữu 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 bám theo URI vẫn cung ứng.
- HEAD: tương tự với GET tuy nhiên response trả về không tồn tại 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 khuôn http.
- PUT: ghi đè toàn bộ vấn đề của đối tượng người tiêu 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 tiêu 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 bám theo 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: tiến hành một bài bác test loop – back bám theo 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 khoác 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 khoác ấn định sở hữu prefix url là api (ví dụ:
happyxoang.com/api/products) - Middleware: khoác ấ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 khoác ấn định này nhập method mapApiRoutes nhập tệp tin app/Providers/RouteServiceProvider.php
Tạo những route nhằm tiến hành 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 bám theo 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 bám theo 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 bám theo 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 rời khỏi nhập laravel cũng tương hỗ tất cả chúng ta một cách khai báo ngắn ngủn gọn gàng hơn:
//Nếu không thích dùng toàn cỗ method nhập apiResource người xem rất có thể hướng đẫn dùng 1 vài ba method bởi hàm only Route::apiResource('products', 'ApiProductController')->only(['index', 'show']); //Hoặc nếu còn muốn vô hiệu lên đường một số ít method ko người sử dụng thì rất 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 vẫn khai báo phía trên, quan trọng đặc biệt nếu như người sử dụng method apiResource thì laravel cũng tương hỗ những method xử lí ứng nhập controller.
Xem thêm: tiểu ra máu ở nữ là bệnh gì
Để tạo nê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 tạo nê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 rời khỏi nếu còn muốn dùng model binding khi tạo nên Resource Controllers thì người sử dụng mệnh lệnh mặt mũi dưới
php artisan make:controller Api/ProductController --api --model=Models/Product
File ProductController tạo nê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 giản dị và đơn giản nhập controller kết phù hợp với model binding và route apiResource khi thiết kế 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 lịch sự loại JSON và sẽ có được status ứng nên chỉ việc return tài liệu rời khỏi là được.
Còn nếu còn muốn tùy biến hóa status trả về thì rất có thể tìm hiểu thêm cơ hội phía bên dưới sở hữu 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ết kế API, chúng ta 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 người sử dụng phần mềm của công ty, laravel đã và đang tương hỗ điều này với Eloquent Resources
Để tạo nê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 …, người xem rất có thể hướng dẫn thêm docs bên trên Laravel.
Authorization
Hiện bên trên sở hữu 3 chế độ Authorize chính:
- HTTP Basic
- JSON Web Token (JWT)
- OAuth2
Tùy nằm trong nhập service của công ty, nhưng mà nên lựa chọn loại Authorize sở hữu cường độ tương thích, nỗ lực lưu giữ nó càng giản dị và đơn giản càng đảm bảo chất lượng.
CORS Policy
Viết API thì cũng cần phải xem xét về CORS là gì?
API Document
Ai cũng biết việc ghi chép API docs là quan trọng, tuy vậy để sở hữu một API docs hoàn hảo cũng tiêu hao không ít thời hạn. Nhất là trong khi dự án công trình nhanh lẹ thì người xem thông thường chỉ nhằm API docs ở tầm mức siêu cơ phiên bản. Tham khảo tăng cơ hội ghi chép API Document.
API document là 1 phần tương tự động như Unit Test vậy – lấy ngắn ngủn nhằm nuôi lâu năm.
Nếu ko được chở che kỹ, thì đến thời điểm maintain hoặc thay cho thay đổi spec thì kết quả tiếp tục cực kỳ thảm khốc, bên dưới đấy là một số trong những cảnh báo khi ghi chép docs:
- Mô miêu tả tương đối đầy đủ về params request: bao gồm những params này, 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 sở hữu bất kể thay cho thay đổi gì.
- Format, cú pháp cần được nhất quán, tế bào miêu tả rõ rệt, đúng chuẩn.
Tham khảo tăng những việc thực hiện API lương bổng cao thú vị bên trên đây
Xem thêm: polyurethane là gì
Bình luận