Your data model has started to stab

Your data model has started to stabilize and you're in a position to create a public API for your web app. You realize it's hard to make significant changes to your API once it's released and want to get as much right as possible up front. Now, the internet has no shortage on opinions on API design. But, since there's no one widely adopted standard that works in all cases, you're left with a bunch of choices: What formats should you accept? How should you authenticate? Should your API be versioned?

In designing an API for Enchant (a Zendesk Alternative), I've tried to come up with pragmatic answers to these questions. My goal is for the Enchant API to be easy to use, easy to adopt and flexible enough to dogfood for our own user interfaces.


Many of the API design opinions found on the web are academic discussions revolving around subjective interpretations of fuzzy standards as opposed to what makes sense in the real world. My goal with this post is to describe best practices for a pragmatic API designed for today's web applications. I make no attempt to satisfy a standard if it doesn't feel right. To help guide the decision making process, I've written down some requirements that the API must strive for:

It should use web standards where they make sense
It should be friendly to the developer and be explorable via a browser address bar
It should be simple, intuitive and consistent to make adoption not only easy but pleasant
It should provide enough flexibility to power majority of the Enchant UI
It should be efficient, while maintaining balance with the other requirements
An API is a developer's UI - just like any UI, it's important to ensure the user's experience is thought out carefully!

Kết quả (Việt) 1:

Mô hình dữ liệu của bạn đã bắt đầu ổn định và bạn đang ở trong một vị trí để tạo ra một API công cộng cho các ứng dụng web của bạn. Bạn nhận ra nó là khó khăn để thực hiện các thay đổi đáng kể với API của bạn một khi nó được phát hành và muốn có được quyền càng nhiều càng tốt lên phía trước. Bây giờ, internet có không thiếu trên các ý kiến về thiết kế API. Tuy nhiên, vì không có tiêu chuẩn rộng rãi được thông qua một trong những hoạt động trong mọi trường hợp, bạn đang trái với một loạt các lựa chọn: định dạng những gì bạn nên chấp nhận? Bạn nên xác thực như thế nào? API của bạn nên versioned?Trong việc thiết kế một API cho Enchant (một thay thế Zendesk), tôi đã cố gắng để đến với thực tế câu trả lời cho những câu hỏi này. Mục tiêu của tôi là để Enchant API để dễ dàng sử dụng, dễ dàng để áp dụng và linh hoạt, đủ để dogfood cho giao diện người dùng của chúng tôi.Nhiều người trong số các ý kiến thiết kế API được tìm thấy trên các trang web là học các cuộc thảo luận xoay quanh chủ quan trong việc giải thích các tiêu chuẩn mờ như trái ngược với những gì làm cho ý thức trong thế giới thực. Mục tiêu của tôi với bài đăng này là để mô tả các thực tiễn tốt nhất cho một API thực dụng được thiết kế cho các ứng dụng web hiện nay. Tôi làm cho không có nỗ lực để đáp ứng một tiêu chuẩn, nếu nó không cảm thấy đúng. Để giúp hướng dẫn các quyết định làm cho quá trình, tôi đã viết xuống một số yêu cầu các API phải phấn đấu cho:Nên sử dụng tiêu chuẩn web mà họ có ý nghĩaNó nên được thân thiện để phát triển và được VRML thông qua một thanh địa chỉ trình duyệtNó nên được đơn giản, trực quan và phù hợp để thực hiện việc áp dụng không chỉ dễ dàng nhưng dễ chịuNó sẽ cung cấp đủ linh hoạt để điện đa số Enchant UINó nên được hiệu quả, trong khi duy trì sự cân bằng với các yêu cầu khácMột API là một nhà phát triển giao diện người dùng - cũng giống như bất kỳ giao diện người dùng, điều quan trọng là để đảm bảo trải nghiệm của người dùng đó là suy nghĩ một cách cẩn thận!

Kết quả (Việt) 2:

Mô hình dữ liệu của bạn đã bắt đầu ổn định và bạn đang ở trong một vị trí để tạo ra một API công cộng cho ứng dụng web của bạn. Bạn nhận ra rằng thật khó để thực hiện thay đổi đáng kể đối với API của bạn khi nó được phát hành và muốn để có được càng nhiều quyền như trước có thể lên. Bây giờ, internet đã không thiếu trên ý kiến về thiết kế API. Nhưng, vì không có ai chấp nhận rộng rãi tiêu chuẩn làm việc trong tất cả các trường hợp, bạn lại với một loạt các lựa chọn: bạn nên chấp nhận định dạng gì? Làm thế nào bạn nên xác thực? API của bạn nên được phiên bản?

Trong thiết kế một API cho Enchant (một Zendesk thay thế), tôi đã cố gắng để đến với câu trả lời cho những câu hỏi thực dụng. Mục tiêu của tôi là cho Enchant API để dễ sử dụng, dễ dàng để chấp nhận và đủ linh hoạt để thử dogfood cho giao diện người dùng riêng của chúng tôi.


Nhiều người trong số những ý kiến thiết kế API được tìm thấy trên trang web đang có các cuộc thảo luận học thuật xoay giải thích xung quanh chủ quan của tiêu chuẩn mờ như trái ngược với những gì có ý nghĩa trong thế giới thực. Mục tiêu của tôi với bài này là để mô tả thực hành tốt nhất cho một API thực dụng được thiết kế cho các ứng dụng web ngày nay. Tôi không cố gắng để đáp ứng một tiêu chuẩn nếu nó không cảm thấy đúng. Để giúp hướng dẫn quá trình ra quyết định, tôi đã viết ra một số yêu cầu mà các API phải phấn đấu:

Có nên sử dụng các tiêu chuẩn web, nơi họ làm cho cảm
Nó phải là thân thiện với các nhà phát triển và được explorable qua một thanh địa chỉ trình duyệt
Cần đơn giản , trực quan và phù hợp để làm cho nhận con nuôi không chỉ dễ dàng nhưng dễ chịu
nó sẽ cung cấp đủ linh hoạt để phần lớn sức mạnh của giao diện người dùng Enchant
nó phải hiệu quả, trong khi duy trì sự cân bằng với các yêu cầu khác
một API là giao diện người dùng của một nhà phát triển - giống như bất kỳ giao diện người dùng, điều quan trọng là để đảm bảo trải nghiệm của người dùng được nghĩ ra một cách cẩn thận!