[API] Discovery

https://developer.wordpress.org/rest-api/using-the-rest-api/discovery/

Khi khách hàng của bạn nói chuyện với một trang web không xác định, bạn sẽ cần khám phá khả năng của trang web đó và cách trang web được định cấu hình. Có một vài bước cho việc này, tùy thuộc vào những gì bạn cần khám phá.

Discovering the API

Bước đầu tiên của việc kết nối với một trang web là tìm hiểu xem trang đó đã bật API hay chưa. Thông thường, bạn sẽ làm việc với các URL từ đầu vào của người dùng, vì vậy trang web bạn đang truy cập có thể là bất kỳ thứ gì. Bước khám phá cho phép bạn xác minh API có sẵn, cũng như chỉ ra cách truy cập nó.

Link Header

Cách ưa thích để xử lý phát hiện là gửi yêu cầu HEAD đến địa chỉ được cung cấp. API REST tự động thêm tiêu đề Liên kết vào tất cả các trang giao diện người dùng giống như sau:

Link: <http://example.com/wp-json/>; rel="https://api.w.org/"

URL này trỏ đến tuyến gốc (/) của API, sau đó được sử dụng cho các bước khám phá tiếp theo.

Đối với các trang web không bật "liên kết cố định đẹp", / wp-json / không được WordPress xử lý tự động. Điều này có nghĩa là các liên kết cố định WordPress bình thường / mặc định sẽ được sử dụng thay thế. Các tiêu đề này trông giống như sau:

Link: <http://example.com/?rest_route=/>; rel="https://api.w.org/"

Khách hàng nên ghi nhớ sự thay đổi này và đảm bảo rằng cả hai tuyến đường có thể được xử lý liền mạch.

Tính năng tự động phát hiện này có thể được áp dụng cho bất kỳ URL nào được cung cấp bởi cài đặt WordPress, vì vậy không cần thêm quá trình xử lý trước đối với đầu vào của người dùng. Vì đây là một yêu cầu HEAD, yêu cầu sẽ an toàn khi gửi một cách mù quáng đến các máy chủ mà không lo gây ra tác dụng phụ.

Element

Đối với các ứng dụng khách có trình phân tích cú pháp HTML hoặc đang chạy trong trình duyệt, phần tương đương của tiêu đề Liên kết được đưa vào của các trang giao diện người dùng thông qua phần tử :

<link rel='https://api.w.org/' href='http://example.com/wp-json/' />

In-browser Javascript can access this via the DOM:

// jQuery method
var $link = jQuery( 'link[rel="https://api.w.org/"]' );
var api_root = $link.attr( 'href' );
 
// Native method
var links = document.getElementsByTagName( 'link' );
var link = Array.prototype.filter.call( links, function ( item ) {
    return ( item.rel === 'https://api.w.org/' );
} );
var api_root = link[0].href;

Đối với ứng dụng khách trong trình duyệt hoặc ứng dụng khách không có quyền truy cập vào tiêu đề HTTP, đây có thể là một cách hữu ích hơn để khám phá API. Điều này tương tự như khám phá nguồn cấp dữ liệu Atom / RSS, vì vậy mã hiện có cho mục đích đó cũng có thể tự động thay vào đó đã thích nghi.

RSD (Really Simple Discovery)

Đối với các máy khách có hỗ trợ khám phá XML-RPC, phương pháp RSD có thể được áp dụng nhiều hơn. Đây là định dạng khám phá dựa trên XML thường được sử dụng cho XML-RPC. RSD có hai bước. Bước đầu tiên là tìm điểm cuối RSD, được cung cấp dưới dạng phần tử :

<link rel="EditURI" type="application/rsd+xml" title="RSD" href="http://example.com/xmlrpc.php?rsd" />

Bước thứ hai là tìm nạp tài liệu RSD và phân tích cú pháp các điểm cuối có sẵn. Điều này liên quan đến việc sử dụng trình phân tích cú pháp XML trên một tài liệu như sau:

<?xml version="1.0" encoding="utf-8"?>
<rsd version="1.0" xmlns="http://archipelago.phrasewise.com/rsd">
  <service>
    <engineName>WordPress</engineName>
    <engineLink>https://wordpress.org/</engineLink>
    <homePageLink>http://example.com/</homePageLink>
    <apis>
      <api name="WordPress" blogID="1" preferred="true" apiLink="http://example.com/xmlrpc.php" />
      <!-- ... -->
      <api name="WP-API" blogID="1" preferred="false" apiLink="http://example.com/wp-json/" />
    </apis>
  </service>
</rsd>

API REST luôn có thuộc tính tên với giá trị bằng WP-API.

RSD là phương pháp tự động phát hiện ít được ưa thích nhất vì một vài lý do. Bước đầu tiên của khám phá dựa trên RSD liên quan đến việc phân tích cú pháp HTML để lần đầu tiên tìm thấy chính tài liệu RSD, tương đương với tự động phát hiện Phần tử . Sau đó, nó liên quan đến một bước khác để phân tích cú pháp tài liệu RSD, yêu cầu trình phân tích cú pháp XML đầy đủ.

Nếu có thể, chúng tôi khuyên bạn nên tránh khám phá dựa trên RSD do sự phức tạp, nhưng các máy khách XML-RPC hiện tại có thể thích sử dụng phương pháp này hơn nếu họ đã bật trình phân tích cú pháp RSD. Đối với các máy khách XML-RPC muốn sử dụng REST API như một cải tiến liên tục cho cơ sở mã, điều này tránh cần phải hỗ trợ các dạng khám phá khác nhau.

Authentication Discovery

Khám phá cũng có sẵn cho các phương pháp xác thực có sẵn thông qua API. Phản hồi của gốc API là một đối tượng mô tả API, bao gồm khóa xác thực:

{
    "name": "Example WordPress Site",
    "description": "YOLO",
    "routes": { ... },
    "authentication": {
        "oauth1": {
            "request": "http://example.com/oauth/request",
            "authorize": "http://example.com/oauth/authorize",
            "access": "http://example.com/oauth/access",
            "version": "0.1"
        }
    }
}

Giá trị xác thực là một ánh xạ (mảng kết hợp) của ID phương thức xác thực đến các tùy chọn xác thực. Các tùy chọn có sẵn ở đây là cụ thể cho chính phương thức xác thực. Xem tài liệu xác thực để biết các tùy chọn cho các phương pháp xác thực cụ thể.

Extension Discovery

Khi bạn đã phát hiện ra API, bước tiếp theo là kiểm tra xem API hỗ trợ những gì. Chỉ mục của API hiển thị mục không gian tên, mục này chứa các phần mở rộng cho API được hỗ trợ.

Đối với các trang web WordPress sử dụng phiên bản 4.4 đến 4.6, chỉ có cơ sở hạ tầng API cơ sở, chứ không phải API đầy đủ với điểm cuối. Điều này cũng bao gồm các điểm cuối oEmbed:

{
    "name": "Example WordPress Site",
    "namespaces": [
        "oembed/1.0/"
    ]
}

Các trang web có sẵn API đầy đủ (tức là có cài đặt WordPress 4.7+ hoặc plugin REST API) sẽ có mục wp / v2 trong không gian tên:

{
    "name": "Example WordPress Site",
    "namespaces": [
        "wp/v2",
        "oembed/1.0/"
    ]
}

Trước khi cố gắng sử dụng bất kỳ điểm cuối cốt lõi nào, bạn nên đảm bảo kiểm tra xem API có được hỗ trợ hay không bằng cách kiểm tra hỗ trợ wp / v2. WordPress 4.4 đã kích hoạt cơ sở hạ tầng API cho tất cả các trang web, nhưng không bao gồm các điểm cuối cốt lõi trong wp / v2. Các điểm cuối cốt lõi đã được thêm vào WordPress 4.7.

Cơ chế tương tự này có thể được sử dụng để phát hiện hỗ trợ cho bất kỳ plugin nào hỗ trợ API REST. Ví dụ: lấy một plugin đăng ký tuyến sau:

<?php
    register_rest_route( 'testplugin/v1', '/testroute', array( /* ... */ ) );
?>

Điều này sẽ thêm không gian tên testplugin / v1 vào chỉ mục:

{
    "name": "Example WordPress Site",
    "namespaces": [
        "wp/v2",
        "oembed/1.0/",
        "testplugin/v1"
    ]
}

Resource Discovery

Kể từ WordPress 5.5, API REST cũng cung cấp cơ chế khám phá để xác định tuyến API REST tương đương với tài liệu hiện tại. Một liên kết được thêm với một liên kết của thay thế và một loại thay thế / json trỏ đến một url API REST. Liên kết được thêm cả dưới dạng tiêu đề Liên kết và phần tử .

Ví dụ: trong phần của trang này, sau sẽ xuất hiện.

<link rel="alternate" type="application/json" href="https://developer.wordpress.org/wp-json/wp/v2/rest-api-handbook/23085">

Các liên kết được thêm vào cho bài đăng, trang và các loại bài đăng tùy chỉnh khác, cũng như các điều khoản và trang tác giả. Các liên kết hiện không được xuất cho các kho lưu trữ bài đăng hoặc kết quả tìm kiếm.

Previous[API] Linking and Embedding Next[API] Authentication

Last updated 3 years ago