http api

Mọi thứ bảng điều khiển làm được, ngay từ terminal của bạn

Một khóa tài khoản. Liệt kê các trang của bạn, triển khai lên chúng, đổi tên, đọc những gì biểu mẫu thu được, xóa đi — bằng HTTP thuần, từ một script, một job CI hay một tác nhân.

Tạo khóa Đọc bản giao kèo

bắt đầu nhanh

Ba câu lệnh

Tạo một khóa trong bảng điều khiển, kiểm tra nó chạy được, rồi đưa một thư mục lên mạng. Khóa nằm trong header Authorization ở mọi lần gọi.

Kiểm tra khóa có chạy không

curl -H "Authorization: Bearer hvs_…" https://harvis.dev/api/v1

Xem tài khoản đang có gì

curl -H "Authorization: Bearer hvs_…" https://harvis.dev/api/v1/sites

Xuất bản một thư mục

curl -X POST https://harvis.dev/api/v1/sites \
  -H "Authorization: Bearer hvs_…" \
  -F "files=@index.html" -F "paths=index.html"

một bản giao kèo

Ứng dụng web và API không thể lệch nhau

Mỗi khả năng được khai báo một lần, trong một tệp, và cả bảng điều khiển lẫn API này đều dựng từ đó. openapi.json được sinh ra từ khai báo ấy, và bản dựng sẽ hỏng nếu hai bên không khớp. Vậy nên đây không phải tài liệu mô tả sản phẩm — nó chính là thứ làm nên sản phẩm.

Mỗi khả năng một cách hiện thực, ứng dụng web và script của bạn gọi cùng một chỗ.
openapi.json được sinh tự động, không bao giờ viết tay, và phục vụ tại /openapi.json.
Bản dựng hỏng ngay khi route, bản giao kèo và tài liệu không còn khớp nhau.

triển khai

Có khóa thì trang là của bạn ngay lập tức

Triển khai không cần tài khoản vẫn chạy và sẽ luôn chạy — bạn nhận một liên kết nhận trang riêng để mở sau. Gửi kèm khóa trong cùng lần gọi thì chẳng còn gì để nhận: trang thuộc tài khoản của bạn ngay từ byte đầu tiên, và không bao giờ hết hạn.

zip -r site.zip . && curl -X POST https://harvis.dev/api/upload \
  -H "Authorization: Bearer hvs_…" \
  -H "Content-Type: application/zip" --data-binary @site.zip

điểm cuối

Toàn bộ bề mặt

Cấu trúc đầy đủ của yêu cầu và phản hồi nằm trong tài liệu OpenAPI.

phương thức	đường dẫn	làm gì
GET	/api/v1	Check that a credential works.
GET	/api/v1/keys	The account's API keys. Revoked keys are not listed.
POST	/api/v1/keys	Create an API key.
DELETE	/api/v1/keys/{keyId}	Revoke an API key. Anything using it stops working immediately.
GET	/api/v1/me	The account a credential belongs to.
GET	/api/v1/sites	List the account's sites, newest first.
POST	/api/v1/sites	Create a site from a folder of files.
DELETE	/api/v1/sites/{id}	Delete a site, its files and its form submissions.
GET	/api/v1/sites/{id}	One site.
PATCH	/api/v1/sites/{id}	Rename a site, change its web address, or both.
POST	/api/v1/sites/{id}/deploy	Replace every file of a site with the uploaded set.
POST	/api/v1/sites/{id}/deploy-token	Issue a new deploy token for a site. The old one stops working immediately.
POST	/api/v1/sites/{id}/deploy/zip	Replace every file of a site from a zip archive sent as the raw request body.
GET	/api/v1/sites/{id}/files	Every file a site is serving.
POST	/api/v1/sites/{id}/files	Add or overwrite individual files, leaving the rest of the site alone.
DELETE	/api/v1/sites/{id}/submissions	Delete every submission for a site, or every one of a single form.
GET	/api/v1/sites/{id}/submissions	One page of a site's form submissions, newest first.
DELETE	/api/v1/sites/{id}/submissions/{submissionId}	Delete one submission.
GET	/api/v1/sites/{id}/submissions/{submissionId}	One submission.
GET	/api/v1/sites/{id}/submissions/csv	Export a site's form submissions as CSV.
POST	/api/v1/sites/{id}/submissions/read	Mark every unread submission as read.
GET	/api/v1/sites/{id}/submissions/summary	How many submissions a site holds, how many are unread, and which forms exist.
POST	/api/v1/sites/import	Create a site by downloading a single page from a known artifact URL.

lỗi

Mọi lỗi đều có cùng một hình dạng

Rẽ nhánh theo mã lỗi, đừng bao giờ theo thông điệp. Mã lỗi thì ổn định; phần chữ là dành cho người đọc log.

{
  "error": {
    "code": "subdomainTaken",
    "message": "That address is already taken. Try another."
  }
}