±à¼ÍƼö: |
±¾ÎÄÀ´×ÔÓÚÈîÒ»·åµÄÍøÂçÈÕÖ¾£¬±¾ÎÄÖØµã½éÉÜlÁËRESTful
APIµÄÉè¼ÆÏ¸½Ú£¬Ì½ÌÖÈçºÎÉè¼ÆÒ»Ì׺ÏÀí¡¢ºÃÓõÄAPI¡£ |
|
ÍøÂçÓ¦ÓóÌÐò£¬·ÖΪǰ¶ËºÍºó¶ËÁ½¸ö²¿·Ö¡£µ±Ç°µÄ·¢Õ¹Ç÷ÊÆ£¬¾ÍÊÇǰ¶ËÉ豸²ã³ö²»ÇÊÖ»ú¡¢Æ½°å¡¢×ÀÃæµçÄÔ¡¢ÆäËûרÓÃÉ豸......£©¡£
Òò´Ë£¬±ØÐëÓÐÒ»ÖÖͳһµÄ»úÖÆ£¬·½±ã²»Í¬µÄǰ¶ËÉ豸Óëºó¶Ë½øÐÐͨÐÅ¡£Õâµ¼ÖÂAPI¹¹¼ÜµÄÁ÷ÐУ¬ÉõÖÁ³öÏÖ"API
First"µÄÉè¼ÆË¼Ïë¡£RESTful APIÊÇĿǰ±È½Ï³ÉÊìµÄÒ»Ì×»¥ÁªÍøÓ¦ÓóÌÐòµÄAPIÉè¼ÆÀíÂÛ¡£ÎÒÒÔǰд¹ýһƪ¡¶Àí½âRESTful¼Ü¹¹¡·£¬Ì½ÌÖÈçºÎÀí½âÕâ¸ö¸ÅÄî¡£
½ñÌ죬ÎÒ½«½éÉÜRESTful APIµÄÉè¼ÆÏ¸½Ú£¬Ì½ÌÖÈçºÎÉè¼ÆÒ»Ì׺ÏÀí¡¢ºÃÓõÄAPI¡£ÎÒµÄÖ÷Òª²Î¿¼ÁËÁ½ÆªÎÄÕ£¨1£¬2£©¡£
Ò»¡¢ÐÒé
APIÓëÓû§µÄͨÐÅÐÒ飬×ÜÊÇʹÓÃHTTPsÐÒé¡£
¶þ¡¢ÓòÃû
Ó¦¸Ã¾¡Á¿½«API²¿ÊðÔÚרÓÃÓòÃû֮ϡ£
Èç¹ûÈ·¶¨APIºÜ¼òµ¥£¬²»»áÓнøÒ»²½À©Õ¹£¬¿ÉÒÔ¿¼ÂÇ·ÅÔÚÖ÷ÓòÃûÏ¡£
Èý¡¢°æ±¾£¨Versioning£©
https://api.example.com/v1/ |
Ó¦¸Ã½«APIµÄ°æ±¾ºÅ·ÅÈëURL¡£
ÁíÒ»ÖÖ×ö·¨ÊÇ£¬½«°æ±¾ºÅ·ÅÔÚHTTPÍ·ÐÅÏ¢ÖУ¬µ«²»Èç·ÅÈëURL·½±ãºÍÖ±¹Û¡£Github²ÉÓÃÕâÖÖ×ö·¨¡£
ËÄ¡¢Â·¾¶£¨Endpoint£©
·¾¶ÓÖ³Æ"ÖÕµã"£¨endpoint£©£¬±íʾAPIµÄ¾ßÌåÍøÖ·¡£
ÔÚRESTful¼Ü¹¹ÖУ¬Ã¿¸öÍøÖ·´ú±íÒ»ÖÖ×ÊÔ´£¨resource£©£¬ËùÒÔÍøÖ·Öв»ÄÜÓж¯´Ê£¬Ö»ÄÜÓÐÃû´Ê£¬¶øÇÒËùÓõÄÃû´ÊÍùÍùÓëÊý¾Ý¿âµÄ±í¸ñÃû¶ÔÓ¦¡£Ò»°ãÀ´Ëµ£¬Êý¾Ý¿âÖÐµÄ±í¶¼ÊÇͬÖּǼµÄ"¼¯ºÏ"£¨collection£©£¬ËùÒÔAPIÖеÄÃû´ÊÒ²Ó¦¸ÃʹÓø´Êý¡£
¾ÙÀýÀ´Ëµ£¬ÓÐÒ»¸öAPIÌṩ¶¯ÎïÔ°£¨zoo£©µÄÐÅÏ¢£¬»¹°üÀ¨¸÷ÖÖ¶¯ÎïºÍ¹ÍÔ±µÄÐÅÏ¢£¬ÔòËüµÄ·¾¶Ó¦¸ÃÉè¼Æ³ÉÏÂÃæÕâÑù¡£
https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees |
Îå¡¢HTTP¶¯´Ê
¶ÔÓÚ×ÊÔ´µÄ¾ßÌå²Ù×÷ÀàÐÍ£¬ÓÉHTTP¶¯´Ê±íʾ¡£
³£ÓõÄHTTP¶¯´ÊÓÐÏÂÃæÎå¸ö£¨À¨ºÅÀïÊǶÔÓ¦µÄSQLÃüÁ¡£
1.GET£¨SELECT£©£º´Ó·þÎñÆ÷È¡³ö×ÊÔ´£¨Ò»Ïî»ò¶àÏ¡£
2.POST£¨CREATE£©£ºÔÚ·þÎñÆ÷н¨Ò»¸ö×ÊÔ´¡£
3.PUT£¨UPDATE£©£ºÔÚ·þÎñÆ÷¸üÐÂ×ÊÔ´£¨¿Í»§¶ËÌṩ¸Ä±äºóµÄÍêÕû×ÊÔ´£©¡£
4.PATCH£¨UPDATE£©£ºÔÚ·þÎñÆ÷¸üÐÂ×ÊÔ´£¨¿Í»§¶ËÌṩ¸Ä±äµÄÊôÐÔ£©¡£
5.DELETE£¨DELETE£©£º´Ó·þÎñÆ÷ɾ³ý×ÊÔ´¡£
»¹ÓÐÁ½¸ö²»³£ÓõÄHTTP¶¯´Ê¡£
1.HEAD£º»ñÈ¡×ÊÔ´µÄÔªÊý¾Ý¡£
2.OPTIONS£º»ñÈ¡ÐÅÏ¢£¬¹ØÓÚ×ÊÔ´µÄÄÄЩÊôÐÔÊǿͻ§¶Ë¿ÉÒԸıäµÄ¡£
ÏÂÃæÊÇһЩÀý×Ó¡£
1.GET /zoos£ºÁгöËùÓж¯ÎïÔ°
2.POST /zoos£ºÐ½¨Ò»¸ö¶¯ÎïÔ°
3.GET /zoos/ID£º»ñȡij¸öÖ¸¶¨¶¯ÎïÔ°µÄÐÅÏ¢
4.PUT /zoos/ID£º¸üÐÂij¸öÖ¸¶¨¶¯ÎïÔ°µÄÐÅÏ¢£¨Ìṩ¸Ã¶¯ÎïÔ°µÄÈ«²¿ÐÅÏ¢£©
5.PATCH /zoos/ID£º¸üÐÂij¸öÖ¸¶¨¶¯ÎïÔ°µÄÐÅÏ¢£¨Ìṩ¸Ã¶¯ÎïÔ°µÄ²¿·ÖÐÅÏ¢£©
6.DELETE /zoos/ID£ºÉ¾³ýij¸ö¶¯ÎïÔ°
7.GET /zoos/ID/animals£ºÁгöij¸öÖ¸¶¨¶¯ÎïÔ°µÄËùÓж¯Îï
8.DELETE /zoos/ID/animals/ID£ºÉ¾³ýij¸öÖ¸¶¨¶¯ÎïÔ°µÄÖ¸¶¨¶¯Îï
Áù¡¢¹ýÂËÐÅÏ¢£¨Filtering£©
Èç¹û¼Ç¼ÊýÁ¿ºÜ¶à£¬·þÎñÆ÷²»¿ÉÄܶ¼½«ËüÃÇ·µ»Ø¸øÓû§¡£APIÓ¦¸ÃÌṩ²ÎÊý£¬¹ýÂË·µ»Ø½á¹û¡£
ÏÂÃæÊÇһЩ³£¼ûµÄ²ÎÊý¡£
1.limit=10£ºÖ¸¶¨·µ»Ø¼Ç¼µÄÊýÁ¿
2.offset=10£ºÖ¸¶¨·µ»Ø¼Ç¼µÄ¿ªÊ¼Î»Öá£
3.page=2&per_page=100£ºÖ¸¶¨µÚ¼¸Ò³£¬ÒÔ¼°Ã¿Ò³µÄ¼Ç¼Êý¡£
4.sortby=name&order=asc£ºÖ¸¶¨·µ»Ø½á¹û°´ÕÕÄĸöÊôÐÔÅÅÐò£¬ÒÔ¼°ÅÅÐò˳Ðò¡£
5.animal_type_id=1£ºÖ¸¶¨É¸Ñ¡Ìõ¼þ
²ÎÊýµÄÉè¼ÆÔÊÐí´æÔÚÈßÓ࣬¼´ÔÊÐíAPI·¾¶ºÍURL²ÎÊýż¶ûÓÐÖØ¸´¡£±ÈÈ磬GET /zoo/ID/animals
Óë GET /animals?zoo_id=ID µÄº¬ÒåÊÇÏàͬµÄ¡£
Æß¡¢×´Ì¬Â루Status Codes£©
·þÎñÆ÷ÏòÓû§·µ»ØµÄ״̬ÂëºÍÌáʾÐÅÏ¢£¬³£¼ûµÄÓÐÒÔÏÂһЩ£¨·½À¨ºÅÖÐÊǸÃ״̬Âë¶ÔÓ¦µÄHTTP¶¯´Ê£©¡£
1.200 OK - [GET]£º·þÎñÆ÷³É¹¦·µ»ØÓû§ÇëÇóµÄÊý¾Ý£¬¸Ã²Ù×÷ÊÇÃݵȵģ¨Idempotent£©¡£
2.201 CREATED - [POST/PUT/PATCH]£ºÓû§Ð½¨»òÐÞ¸ÄÊý¾Ý³É¹¦¡£
3.202 Accepted - [*]£º±íʾһ¸öÇëÇóÒѾ½øÈëºǫ́ÅŶӣ¨Òì²½ÈÎÎñ£©
4.204 NO CONTENT - [DELETE]£ºÓû§É¾³ýÊý¾Ý³É¹¦¡£
5.400 INVALID REQUEST - [POST/PUT/PATCH]£ºÓû§·¢³öµÄÇëÇóÓдíÎ󣬷þÎñÆ÷ûÓнøÐÐн¨»òÐÞ¸ÄÊý¾ÝµÄ²Ù×÷£¬¸Ã²Ù×÷ÊÇÃݵȵġ£
6.401 Unauthorized - [*]£º±íʾÓû§Ã»ÓÐȨÏÞ£¨ÁîÅÆ¡¢Óû§Ãû¡¢ÃÜÂë´íÎ󣩡£
7.403 Forbidden - [*] ±íʾÓû§µÃµ½ÊÚȨ£¨Óë401´íÎóÏà¶Ô£©£¬µ«ÊÇ·ÃÎÊÊDZ»½ûÖ¹µÄ¡£
8.404 NOT FOUND - [*]£ºÓû§·¢³öµÄÇëÇóÕë¶ÔµÄÊDz»´æÔڵļǼ£¬·þÎñÆ÷ûÓнøÐвÙ×÷£¬¸Ã²Ù×÷ÊÇÃݵȵġ£
9.406 Not Acceptable - [GET]£ºÓû§ÇëÇóµÄ¸ñʽ²»¿ÉµÃ£¨±ÈÈçÓû§ÇëÇóJSON¸ñʽ£¬µ«ÊÇÖ»ÓÐXML¸ñʽ£©¡£
10.410 Gone -[GET]£ºÓû§ÇëÇóµÄ×ÊÔ´±»ÓÀ¾Ãɾ³ý£¬ÇÒ²»»áÔٵõ½µÄ¡£
11.422 Unprocesable entity - [POST/PUT/PATCH]
µ±´´½¨Ò»¸ö¶ÔÏóʱ£¬·¢ÉúÒ»¸öÑéÖ¤´íÎó¡£
12.500 INTERNAL SERVER ERROR - [*]£º·þÎñÆ÷·¢Éú´íÎó£¬Óû§½«ÎÞ·¨ÅжϷ¢³öµÄÇëÇóÊÇ·ñ³É¹¦¡£
״̬ÂëµÄÍêÈ«Áбí²Î¼ûÕâÀï¡£
°Ë¡¢´íÎó´¦Àí£¨Error handling£©
Èç¹û״̬ÂëÊÇ4xx£¬¾ÍÓ¦¸ÃÏòÓû§·µ»Ø³ö´íÐÅÏ¢¡£Ò»°ãÀ´Ëµ£¬·µ»ØµÄÐÅÏ¢Öн«error×÷Ϊ¼üÃû£¬³ö´íÐÅÏ¢×÷Ϊ¼üÖµ¼´¿É¡£
{
error: "Invalid API key"
}
|
¾Å¡¢·µ»Ø½á¹û
Õë¶Ô²»Í¬²Ù×÷£¬·þÎñÆ÷ÏòÓû§·µ»ØµÄ½á¹ûÓ¦¸Ã·ûºÏÒÔϹ淶¡£
1.GET /collection£º·µ»Ø×ÊÔ´¶ÔÏóµÄÁÐ±í£¨Êý×飩
2.GET /collection/resource£º·µ»Øµ¥¸ö×ÊÔ´¶ÔÏó
3.POST /collection£º·µ»ØÐÂÉú³ÉµÄ×ÊÔ´¶ÔÏó
4.PUT /collection/resource£º·µ»ØÍêÕûµÄ×ÊÔ´¶ÔÏó
5.PATCH /collection/resource£º·µ»ØÍêÕûµÄ×ÊÔ´¶ÔÏó
6.DELETE /collection/resource£º·µ»ØÒ»¸ö¿ÕÎĵµ
Ê®¡¢Hypermedia API
RESTful API×îºÃ×öµ½Hypermedia£¬¼´·µ»Ø½á¹ûÖÐÌṩÁ´½Ó£¬Á¬ÏòÆäËûAPI·½·¨£¬Ê¹µÃÓû§²»²éÎĵµ£¬Ò²ÖªµÀÏÂÒ»²½Ó¦¸Ã×öʲô¡£
±ÈÈ磬µ±Óû§Ïòapi.example.comµÄ¸ùĿ¼·¢³öÇëÇ󣬻áµÃµ½ÕâÑùÒ»¸öÎĵµ¡£
{"link": {
"rel": "collection https://www.example.com/zoos",
"href": "https://api.example.com/zoos",
"title": "List of zoos",
"type": "application/vnd.yourformat+json"
}}
|
ÉÏÃæ´úÂë±íʾ£¬ÎĵµÖÐÓÐÒ»¸ölinkÊôÐÔ£¬Óû§¶ÁÈ¡Õâ¸öÊôÐÔ¾ÍÖªµÀÏÂÒ»²½¸Ãµ÷ÓÃʲôAPIÁË¡£rel±íʾÕâ¸öAPIÓëµ±Ç°ÍøÖ·µÄ¹ØÏµ£¨collection¹ØÏµ£¬²¢¸ø³ö¸ÃcollectionµÄÍøÖ·£©£¬href±íʾAPIµÄ·¾¶£¬title±íʾAPIµÄ±êÌ⣬type±íʾ·µ»ØÀàÐÍ¡£
Hypermedia APIµÄÉè¼Æ±»³ÆÎªHATEOAS¡£GithubµÄAPI¾ÍÊÇÕâÖÖÉè¼Æ£¬·ÃÎÊapi.github.com»áµÃµ½Ò»¸öËùÓпÉÓÃAPIµÄÍøÖ·ÁÐ±í¡£
{
"current_user_url": "https://api.github.com/user",
"authorizations_url": "https://api.github.com/authorizations",
// ...
}
|
´ÓÉÏÃæ¿ÉÒÔ¿´µ½£¬Èç¹ûÏë»ñÈ¡µ±Ç°Óû§µÄÐÅÏ¢£¬Ó¦¸ÃÈ¥·ÃÎÊapi.github.com/user£¬È»ºó¾ÍµÃµ½ÁËÏÂÃæ½á¹û¡£
{
"message": "Requires authentication",
"documentation_url": "https://developer.github.com/v3"
}
|
ÉÏÃæ´úÂë±íʾ£¬·þÎñÆ÷¸ø³öÁËÌáʾÐÅÏ¢£¬ÒÔ¼°ÎĵµµÄÍøÖ·¡£
ʮһ¡¢ÆäËû
£¨1£©APIµÄÉí·ÝÈÏÖ¤Ó¦¸ÃʹÓÃOAuth 2.0¿ò¼Ü¡£
£¨2£©·þÎñÆ÷·µ»ØµÄÊý¾Ý¸ñʽ£¬Ó¦¸Ã¾¡Á¿Ê¹ÓÃJSON£¬±ÜÃâʹÓÃXML¡£ |