Posted 2021-05-01 楂樺彲鐢ㄦ灦鏋?/a> AP

鑹ソ璁捐鐨凙PI = 蹇箰鐨勭▼搴忓憳 馃槂銆?/span>

搴旂敤绋嬪簭鎺ュ彛锛圓PI锛夋槸涓€绉嶆帴鍙ｏ紝瀹冭搴旂敤绋嬪簭鍙互杞绘澗鍦颁娇鐢ㄥ彟涓€涓簲鐢ㄧ▼搴忕殑鏁版嵁鍜岃祫婧愶紝API 瀵逛簬涓€涓骇鍝佹垨鍏徃鐨勬垚鍔熻嚦鍏抽噸瑕併€?/p>

濡傛灉娌℃湁 API锛屼綘澶ч儴鍒嗗枩娆㈢殑杞欢浠婂ぉ灏变笉浼氬瓨鍦ㄣ€備緥濡傦紝Google Maps API 鍙互璁╀綘鍦?app 鎴?Web 搴旂敤涓娇鐢?Google Maps銆傚鏋滄病鏈夊畠锛屼綘灏嗕笉寰椾笉璁捐鍜屽紑鍙戣嚜宸辩殑鍦板浘鏁版嵁搴撱€傝繖鏍风殑璇濓紝鍦ㄥ湴鍥句笂鏄剧ず涓€涓綅缃渶瑕佽姳璐瑰灏戞椂闂达紵

涓轰粈涔堣浣跨敤 API锛?/strong>

1. API 鍙互璁╁閮ㄥ簲鐢ㄨ闂偍鐨勮祫婧?/p>

2. API 鎵╁睍浜嗗簲鐢ㄧ▼搴忕殑鍔熻兘

3. API 鍏佽寮€鍙戣€呴噸鐢ㄥ簲鐢ㄩ€昏緫

4. API 鏄嫭绔嬩簬骞冲彴鐨勶紝瀹冧滑浼犻€掓暟鎹笉鍙楄姹傚钩鍙扮殑褰卞搷

鍦ㄥぇ澶氭暟瀹為檯鍦烘櫙涓紝鏁版嵁妯″瀷 宸茬粡瀛樺湪锛屼絾鐢变簬鎴戜滑灏嗚璁?API 璁捐鏈€浣冲疄璺碉紝鎴戝皢浠庡ご寮€濮嬭璧枫€?/span>

鏁版嵁寤烘ā涓庣粨鏋勫寲

浠?API 涓轰腑蹇冨鎮ㄧ殑鏁版嵁杩涜寤烘ā锛屾槸璁捐鏄撲簬鍒涘缓銆佺淮鎶ゅ拰鏇存柊 API 鐨勭涓€姝?/p>

鍦ㄨ璁?API 鏃讹紝灏介噺鑰冭檻浣跨敤閫氱敤鐨勬湳璇紝鑰屼笉鏄娇鐢ㄥ唴閮ㄧ殑澶嶆潅涓氬姟鏈锛屽洜涓鸿繖浜涙湳璇湪鍏徃澶栧彲鑳戒笉涓轰汉鎵€鐭ャ€備綘鐨?API 鍙兘浼氬澶栧紑鏀撅紝浠ュ厑璁稿閮ㄥ紑鍙戜汉鍛樹娇鐢ㄤ綘鐨?API 寮€鍙戜粬浠嚜宸辩殑搴旂敤銆傞€氳繃浣跨敤閫氱敤鏈锛屼綘鍙互纭繚浣跨敤 API 鐨勫紑鍙戜汉鍛樻槗浜庝簡瑙ｄ綘鐨?API锛屽苟鑳藉揩閫熶笂鎵嬨€?/p>

鍋囪鍒颁綘姝ｅ湪寤虹珛涓€涓棬鎴风綉绔欙紝璁╃敤鎴风偣璇勪笉鍚屼綔鑰呯殑涔︾睄銆備綘鐨勫叕鍙稿彲鑳戒細浣跨敤鐗瑰畾鐨勬湳璇紝濡傚垱浣滆€呫€佸垱浣溿€佺郴鍒楃瓑鏉ユ寚浠ｅ浘涔︿綔鑰呫€佷功绫嶅拰绯诲垪銆備絾涓轰簡绠€鍗曡捣瑙侊紝骞舵柟渚垮閮ㄥ簲鐢ㄥ紑鍙戣€呬娇鐢ㄤ綘鐨?API锛屼娇鐢ㄩ€氱敤鐨勬蹇佃€屼笉鏄叕鍙哥壒瀹氱殑鏈鏉ュ垱寤?API 璺緞銆?/p>

https://api.domain.com/authors https://api.domain.com/authors/{id}/books

杩欐湁鍔╀簬鏂扮殑寮€鍙戜汉鍛樺揩閫熶簡瑙ｄ綘鐨?API 鏄粈涔堬紝浠ュ強濡備綍閬嶅巻浣犵殑鏁版嵁妯″瀷銆?/p>

缂栧啓闈㈠悜璧勬簮鐨?API

搴旂敤绋嬪簭闇€瑕佽闂綘鐨勮祫婧愩€傜淮鎶や竴涓祫婧愬眰娆＄粨鏋勫彲浠ュ府鍔╀綘鏇村ソ鍦版瀯寤?API銆傝祫婧愬眰娆＄粨鏋勬槸鎸囪矾寰勪腑鐨勬瘡涓妭鐐癸紝瀹冪敱涓€涓泦鍚堟垨涓€涓祫婧愮粍鎴愩€?/p>

璧勬簮鍙互鏄竴涓崟涓€鐨勬暟鎹紝渚嬪锛屼笂闈緥瀛愪腑鐨勪綔鑰呯畝浠嬨€?/p>

闆嗗悎鏄寚涓€涓祫婧愮殑闆嗗悎锛屽湪鎴戜滑鐨勪緥瀛愪腑锛屽畠鍙互鏄竴涓綔鑰呮墍鍐欑殑涔︾殑鍒楄〃銆?/p>

鍚堥€傜殑璧勬簮灞傛缁撴瀯鍙互鏄細

Base Path -> 浣滆€?nbsp;(闆嗗悎) -> profile (璧勬簮)Base Path -> 浣滆€?nbsp;(闆嗗悎) -> 涔?nbsp;(闆嗗悎) -> 涔?nbsp;(璧勬簮)

灞傛缁撴瀯闇€瑕佷繚鎸佷竴鑷达紝浠ョ‘淇濆紑鍙戜汉鍛樺湪灏嗗叾搴旂敤绋嬪簭鎺ュ叆 API 鏃堕亣鍒扮殑闂鏈€灏戙€?/p>

涓轰簡淇濇寔绠€鍗曟€у拰涓€鑷存€э紝杩欓噷鏈変竴浜涙寚瀵煎師鍒欏彲浠ュ府鍔╀綘锛?/p>

1. 鍛藉悕闆嗗悎鍜岃祫婧愭椂浣跨敤缇庡紡鑻辫锛堜緥濡傦細color 鑰屼笉鏄?colour锛?/p>

2. 閬垮厤鎷煎啓閿欒

3. 浣跨敤鏇寸畝鍗曘€佹洿甯哥敤鐨勮瘝鏉ヤ繚鎸佹竻鏅帮紝渚嬪 delete 鑰屼笉鏄?remove

4. 濡傛灉浣犱娇鐢ㄧ殑璧勬簮涓庡叾浠?API 浣跨敤鐨勮祫婧愮浉鍚岋紝璇蜂娇鐢ㄧ浉鍚岀殑鏈浠ヤ繚鎸佷竴鑷淬€?/p>

5. 瀵归泦鍚堜娇鐢ㄥ鏁板舰寮忥紙渚嬪锛歛uthors銆乥ooks 绛夛級銆?/p>

RESTful 鎺ュ彛

HTTP 褰㈠紡鐨?API 鏈€骞挎硾鎺ュ彈鐨勬爣鍑嗘槸 REST(Representational State Transfer)銆傚畠鍩烘湰涓婃剰鍛崇潃姣忎釜 URL 浠ｈ〃涓€涓璞°€?/p>

API 鐩殑鍙互鏄互涓嬩箣涓€锛?/p>

1. 鍒涘缓鏁版嵁 Create

2. 璇诲彇鏁版嵁 Read

3. 鏇存柊鏁版嵁 Update

4. 鍒犻櫎鏁版嵁 Delete

CRUD锛佺寽瀵逛簡!

API 閫氳繃浣跨敤涓€缁?HTTP 鍛戒护鏉ュ鐞嗭紝杩欎簺鍛戒护瀹氫箟浜嗚姹傜殑鎬ц川鍜屽畠搴旇鍋氫粈涔堛€?/p>

GET 浠?API 涓绱㈡暟鎹€傚畠瑕佹眰浠?API 涓幏鍙栨暟鎹殑琛ㄧず銆侴ET璇锋眰鍙互鍖呭惈鏌ヨ鍙傛暟锛屼互杩囨护浠嶢PI鎺ユ敹鐨勭粨鏋溿€?/p>

POST 鍚?API 鎻愪氦涓€鏉¤褰曪紝璇ヨ褰曞皢鍦ㄦ暟鎹簱涓垱寤轰竴涓祫婧愩€?/p>

PUT 涓€鑸敤浜庢洿鏂版湇鍔″櫒涓婄殑鐜版湁璧勬簮銆?/p>

DELETE 浠庢湇鍔″櫒涓婂垹闄や竴涓祫婧愩€?/p>

API 鐗堟湰鎺у埗

搴旂敤绋嬪簭鍜?API 鐨勭敓鍛藉懆鏈熻秺闀匡紝搴旂敤鍜?API 瀵圭敤鎴风殑鎵胯灏辫秺澶с€傚湪鏌愪釜鏃堕棿鐐逛笂锛屼綘鐨?API 灏嗛渶瑕佷慨鏀癸紝鍥犱负浣犳棤娉曢瑙侀殢鐫€闇€姹傚拰涓氬姟鏀跨瓥鑰屽彂鐢熺殑鍙樺寲銆?/p>

鍥犳闇€瑕佸 API 杩涜鏇存敼銆備絾鏄?API 鍙兘宸茬粡鏈変竴涓垨澶氫釜寮€鍙戣€呭湪浣跨敤浜嗭紝鎵€浠ワ紝閲嶈鐨勬槸锛屼綘鎵€鍋氱殑鏇存敼涓嶄細鐮村潖浣犵殑鍚堜綔浼欎即寮€鍙戣€呯殑搴旂敤銆?/p>

浜嗚В涓昏鍜屾瑕佹洿鏂?/strong>

灏忕増鏈崌绾э紙Minor锛?/strong>锛氬綋鍙樻洿涓嶄細鐮村潖瀹㈡埛绔簲鐢ㄧ▼搴忕殑杩愯鏃讹紝鍙互浣跨敤灏忕増鏈崌绾э紝渚嬪娣诲姞鍙€夊瓧娈垫垨鏀寔闄勫姞鍙傛暟銆傝繖鏃跺€欎綘鍙互涓轰綘鐨?API 澧炶灏忕増鏈€?/p>

澶х増鏈崌绾э紙Major锛?/strong>锛氭槸閭ｄ簺鑲畾浼氱牬鍧忕幇鏈夊鎴风搴旂敤鐨勭増鏈紝姣斿鍦ㄨ姹傚弬鏁颁腑娣诲姞涓€涓柊鐨勫繀闇€鍙傛暟锛屾垨鏀瑰彉杩斿洖缁撴灉涓殑瀛楁銆?/p>

鍙互閫氳繃澶氱鏂瑰紡鏉ュ API 杩涜鐗堟湰鎺у埗銆?/p>

鏈€甯歌鐨勬柟娉曟槸灏嗙増鏈寘鍚湪 URI 涓€?/p>

https://api.domain.com/v1.0/authors

鍙﹀涓€绉嶆柟娉曟槸浣跨敤鍩轰簬鏃ユ湡鐨勭増鏈帶鍒躲€俇RI 涓寘鎷皢鐗堟湰鍙戝竷鏃ユ湡銆傚簲鐢ㄧ▼搴忓紑鍙戜汉鍛樺彲浠ュ緢鏂逛究浜嗚В API 鏇存敼鐨勯鐜囥€?/p>

https://api.domain.com/2020-06-15/authors

鍙︿竴绉嶆柟娉曟槸鍦ㄨ姹傛爣澶翠腑鍖呭惈 API 鐗堟湰銆?/p>

https://api.domain.com/authors x-api-version锛歷1

鏈€鎺ㄨ崘鍜屾帴鍙楃殑鐗堟湰鎺у埗鏂瑰紡鏄紝鍦║RI 涓娇鐢ㄧ増鏈悕绉般€?/p>

鍒嗛〉

鍦ㄦ暟鎹噺瓒婃潵瓒婂ぇ鐨勪笘鐣岄噷锛屼笉鍙兘鍦ㄤ竴涓睆骞曚笂鍚屾椂鏄剧ず鎵€鏈夌殑鏁版嵁銆傛墍浠ワ紝璁╃敤鎴峰湪鍐嶆璇锋眰鏁版嵁涔嬪墠锛屽厛鍙栧埌涓€瀹氭暟閲忕殑缁撴灉锛岃繖涓€鐐瑰緢閲嶈銆傝繖灏辨槸鎵€璋撶殑鍒嗛〉锛岃繑鍥炵殑鏁版嵁闆嗗彨鍋氶〉闈€?/p>

寤鸿浣犲湪璇锋眰鍜岃繑鍥炵粨鏋滀腑浣跨敤鐗瑰畾鐨勬湳璇潵鍚敤 API 涓殑鍒嗛〉鍔熻兘銆傝繖浜涙湳璇湁

1. STRING page_token锛堝湪璇锋眰涓彂閫侊級

2. STRING next_page_token锛堢敱 API 杩斿洖锛?/p>

3. INT page_size锛堝湪璇锋眰涓彂閫侊級

page_token 璇锋眰 API 闇€瑕佽繑鍥炲摢涓〉闈€傝繖閫氬父鏄竴涓瓧绗︿覆銆傚浜庣涓€娆PI璋冪敤锛宲age_token = "1"

page_size 瀹氫箟浜嗚繑鍥炵粨鏋滀腑搴旇杩斿洖澶氬皯鏉¤褰曘€備緥濡俻age_size = 100锛屽湪API璋冪敤涓渶澶氳繑鍥?00鏉¤褰曘€?/p>

next_page_token 瀹氫箟浜嗙炕椤电殑涓嬩竴涓?token銆傚鏋滃湪page_token = "1" 涔嬪悗鏈夐澶栫殑鏁版嵁锛岃繑鍥炵殑鍊兼槸搴斿綋鏄?nbsp; next_page_token="2"

濡傛灉娌℃湁鏇村鐨勬暟鎹彲鐢紝鑰屼笖鐢ㄦ埛宸茬粡鍒拌揪鏁版嵁鐨勭粓鐐癸紝鍒欒繑鍥炰竴涓┖鐧藉€?next_page_token="" 銆?/p>

杩欎簺灏辨槸璁捐 API 鐨勬渶浣冲疄璺点€傚畠璁╀綘鐨?API 鏇村仴澹€佺畝娲佸苟鏄撲簬涓庡叾浠栧簲鐢ㄧ▼搴忛泦鎴愩€?/p>

璇疯浣忋€?/p>

鑹ソ璁捐鐨凙PI = 蹇箰鐨勭▼搴忓憳 馃槂銆?/span>

鑻辨枃鍘熸枃锛?/p>

https://codeburst.io/best-practices-api-design-61d4697d17ff

鍙傝€冮槄璇伙細

• 
  

• 
  

• 
  

楂樺彲鐢ㄦ灦鏋?/strong>

鏀瑰彉浜掕仈缃戠殑鏋勫缓鏂瑰紡