API 與 RESTful API

API 是甚麼

工程師的方式去說明某個功能的使用方法

目的: 寫清楚這個功能要怎麼用

ex:

http://localhost:8080/getProduct

@RestController
public class ProductController{
    // 取得商品列表
    @RequestMapping("/getProduct")
    public Product getProduct(){
        //...
    }
    // 創建商品
    @RequestMapping("/createProduct")
    public Product createProduct(){
        //...
    }

}

衍生的問題是:

GET? POST?

可以指定一次取多少個商品?

回傳json格式?

商品關鍵字查詢功能?

因此需要API文件

API文件

取得商品列表的API

前端

GET http://localhost:8080/getProduct?size=10

後端

@RequestMapping("getProduct")
public Product getProduct(@RequestParam Integer size, 
                          @RequestParam(required = false) String search){
    // ...
}

API 常見說法

這個getProduct API 怪怪的 ,可以幫我看一下嗎?
你可以call getProduct API /打 getProduct API (你可以對 /getProduct 這個url路徑去發起一個http request)

REST 風格 (只是一種約定俗成的習慣 ,不是標準規範)

目的: 簡化溝通成本

如果你所設計的API 符合REST 風格 ,那麼你所設計的API 就是RESTful API

`使用 http method 表示動作`

http method	對應的資料庫操作	說明
POST	Create (新增)	新增一個資源
GET	Read (查詢)	取得一個資源
PUT	Update (修改)	更新一個已存在的資源
DELETE	Delete (刪除)	刪除一個資源

http method 對應到資料庫的CRUD 增查改刪

`使用url路徑描述資源之間的階層關係`

@RequestParam 與 @PathVariable

http method + url 路徑	說明
GET /users	取得所有user
GET /users/123	取得 user id為123 的user
GET /users/123/articles	取得 user id為123 的user 所寫的所有文章
GET /users/123/articles/456	取得 user id為123 的user 所寫的 article id 為 456的文章
GET /users/123/videos	取得 user id為123 的user 所錄的所有影片
GET /users/123/videos/789	取得 user id為123 的user 所錄的 video id 為789 的影片
GET /users/100	取得 user id為100 的user

`response body 返回 json 或是 xml 格式`

在class 上面加上@RestController 方法的返回值 ,會以 json 格式返回

@RestController = Rest + Controller ,符合REST的Controller

如何設計出RESTful API?

使用http method 表示動作
使用url路徑描述資源之間的階層關係
response body 返回json或是 xml格式

設計 Student 的 RESTful API

public class Student{
    Integer id;
    String name;
}

http method	url路徑	對應的資料庫操作	說明
POST	/students	Create (新增)	創建一個新的Student
GET	/students/123	Read (查詢)	查詢 studnet id 為123 的資訊
PUT	/students/123	Update (修改)	更新 studnet id 為123 的資訊
DELETE	/students/123	Delete (刪除)	刪除 studnet id 為123 的 Student

實作 Student

需要加上設定限制只能使用 POST

@PostMapping("/students") 等同於 @RequestMapping(value = "/students", method = RequestMethod.POST)

其他設定用法如 @GetMapping , @PutMapping 都是相同概念

@RestController
public class StudentController {
    @PostMapping("/students")
// @RequestMapping(value = "/students", method = RequestMethod.POST) 
    public String Create(@RequestBody Student student) {
        return "執行資料庫的 create 操作";
    }
}

Student 其他功能以此類推

import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class StudentController {
    @PostMapping("/students")
    public String create(@RequestBody Student student) {
        return "執行資料庫的 Create 操作";
    }

    @GetMapping("/students/{studentId}")
    public String read(@PathVariable Integer studentId) {
        return "執行資料庫的 Read 操作";
    }

    @PutMapping("/students/{studentId}")
    public String update(@PathVariable Integer studentId ,
                         @RequestBody Student student) {
        return "執行資料庫的 Update 操作";
    }

    @DeleteMapping("/students/{studentId}")
    public String delete(@PathVariable Integer studentId) {
        return "執行資料庫的 Delete 操作";
    }
}