API nền tảng khóa học dùng GraphQL thường khiến người mới kẹt ngay ở trang tài liệu. GraphQL là cách ứng dụng hỏi đúng phần dữ liệu cần lấy. Chúng tôi thường bắt đầu bằng việc xác định luồng kinh doanh, rồi mới nhìn tới câu lệnh kỹ thuật.
Cách đọc này tránh một lỗi khá quen. Đội phát triển thấy nhiều nhóm API nên thử lần lượt, dù chưa biết hệ thống cần trao đổi dữ liệu gì. Kết quả là mã chạy được, song luồng bán khóa học vẫn chưa liền mạch.
Chuẩn GraphQL của API nền tảng khóa học và phần REST
Trước tiên, bạn cần nhận ra tài liệu đang dùng hai cách giao tiếp. Việc phân biệt này quyết định ứng dụng sẽ gửi yêu cầu đến đâu. Nó cũng giúp đội ngũ không áp một cách xử lý cho mọi dịch vụ.
Tài liệu của API nền tảng khóa học Mona.Academy, nền tảng SaaS bán khóa học online của The MONA Group, chủ yếu dùng GraphQL. SaaS nghĩa là phần mềm được cung cấp như một dịch vụ. Người dùng đăng ký xong sẽ có website bán khóa học mang thương hiệu và tên miền riêng.
API nền tảng khóa học dùng GraphQL qua endpoint /graphql/. Endpoint nói dễ hiểu là địa chỉ tiếp nhận yêu cầu từ ứng dụng khác. Cùng một địa chỉ, ứng dụng có thể mô tả phần dữ liệu mình đang cần.
Cách tổ chức ấy hợp với màn hình phải ghép dữ liệu, nên đội lập trình cần viết rõ nhu cầu. Nếu hỏi rộng hơn mức cần thiết, lợi thế của GraphQL sẽ bị bỏ phí.
Phân biệt dịch vụ GraphQL và REST
Một số dịch vụ còn dùng REST. REST cũng là cách các phần mềm trao đổi dữ liệu, nhưng thường chia yêu cầu theo địa chỉ và tác vụ. Vì vậy, thấy /graphql/ vẫn chưa đủ. Bạn cần xem chỉ dẫn của từng dịch vụ.
Tách lớp kết nối theo giao thức
Chúng tôi hay tách lớp kết nối theo giao thức ngay từ đầu. Cách làm này giữ mã GraphQL và REST ở những chỗ dễ nhận biết. Góc nhìn về kiến trúc microservices cho doanh nghiệp cũng giúp bạn hiểu vì sao ranh giới dịch vụ cần được ghi rõ.
Với người chưa lập trình, khác biệt này cho biết việc tích hợp vẫn cần đội kỹ thuật đọc tài liệu. Bạn có thể xem trang Mona Academy để hiểu bối cảnh nền tảng trước khi bàn sâu về kết nối.
Chúng tôi không khuyên đoán giao thức từ tên nhóm API. Hãy nhìn đúng phần tài liệu của dịch vụ đang dùng. Một ghi chú nhỏ về GraphQL hay REST sẽ tiết kiệm nhiều lần sửa mã về sau.
Đọc tài liệu API nền tảng khóa học theo thứ tự nào
Tài liệu công khai và có hai ngôn ngữ, nên cả đội kỹ thuật lẫn người phụ trách vận hành đều có thể đối chiếu. Bạn đừng đọc từ đầu đến cuối như một cuốn sách. Hãy bắt đầu từ việc doanh nghiệp đang muốn kết nối.
Trước khi mở tài liệu API Mona.Academy, chúng tôi thường viết một câu rất ngắn về API nền tảng khóa học. Ví dụ, website cần làm việc với khóa học hay đơn hàng. Câu này giữ cả buổi đọc tài liệu đi đúng hướng.
Chín nhóm API cần đối chiếu
Tài liệu chia thành chín nhóm API. Mỗi nhóm tương ứng với một mảng nghiệp vụ mà ứng dụng có thể cần tìm hiểu. Danh sách đầy đủ gồm:
- xác thực;
- khóa học;
- đơn hàng và thanh toán;
- nâng cấp và bảng giá (SAAS);
- affiliate;
- email marketing;
- blog, content và CMS;
- hóa đơn;
- quản lý tên miền.
Chọn nhóm theo mục tiêu kinh doanh
Nhóm xác thực nên được nhận diện trước khi ghép một luồng có trao đổi dữ liệu. Xác thực là bước hệ thống kiểm tra bên gửi yêu cầu là ai. Nếu tài liệu có nhắc JWT, hãy hiểu đó là một dạng mã mang thông tin xác thực. Sau đó, làm đúng hướng dẫn được công bố.
Sau đó, bạn đi vào nhóm sát với mục tiêu kinh doanh. Luồng bán hàng sẽ khiến đội ngũ quan tâm đến khóa học, đơn hàng và thanh toán. Việc quản trị dịch vụ lại dẫn tới nâng cấp, bảng giá, hóa đơn hoặc tên miền.
Mỗi lần chuyển nhóm, chúng tôi kiểm tra lại giao thức. Nhóm đang xem có đi qua GraphQL? Dịch vụ này dùng REST? Đừng lấy cách gọi của phần trước để áp sang phần sau.
Bước kế tiếp là khoanh một yêu cầu nhỏ để thử cách đọc. Chẳng hạn, đội kỹ thuật chỉ xác định dữ liệu nào thuộc nhóm khóa học. Những gì tài liệu không nêu thì để trống, thay vì tự đặt tên rồi chờ hệ thống hiểu.
Theo dõi luồng dữ liệu và giả định
Nếu dữ liệu sau này còn đi vào CRM, bạn nên vẽ thêm đường đi của nó. CRM là nơi doanh nghiệp lưu và theo dõi quan hệ với khách hàng. Bài về đồng bộ dữ liệu CRM với data pipeline giải thích rõ hơn phần luân chuyển ấy.
Data pipeline tức là chuỗi bước đưa dữ liệu từ nơi này sang nơi khác. Khái niệm này không khẳng định Mona.Academy có kết nối CRM sẵn. Nó chỉ giúp đội dự án thấy phần nào thuộc API nền tảng khóa học, phần nào do hệ thống riêng đảm nhiệm.
Chúng tôi cũng ghi riêng các câu hỏi chưa có đáp án. Cách xử lý JWT, trường dữ liệu bắt buộc hay phản hồi lỗi đều phải bám tài liệu tương ứng. Một giả định chưa kiểm chứng dễ biến thành lỗi khó dò khi ghép nhiều nhóm.
Ca tích hợp API nền tảng khóa học hay gặp nhất
Đọc xong từng nhóm vẫn chưa đủ, vì phần mềm luôn chạy theo luồng. Một ca tích hợp thường chạm nhiều mảng nghiệp vụ liên tiếp. Người mới sẽ dễ theo hơn nếu nhìn từ việc khách đang làm trên website.
Luồng bán khóa học và nội dung
Với luồng bán khóa học, ba nhóm dễ được đặt cạnh nhau là xác thực, khóa học, đơn hàng và thanh toán. Thứ tự xử lý cụ thể phải theo tài liệu. Chúng tôi chỉ dùng nhóm nghiệp vụ để vẽ bản đồ trước khi viết mã.
Bản đồ đó nên ghi đầu vào, điểm xử lý và nơi nhận kết quả. Đây là cách gọi phổ thông cho đường đi của dữ liệu. Người vận hành nhờ vậy trao đổi được với lập trình viên. Họ không cần hiểu cú pháp GraphQL.
Một ca khác nằm ở nội dung và chăm sóc người học. Khi ấy, đội dự án sẽ tìm trong nhóm email marketing cùng blog, content và CMS. CMS tức là hệ thống quản lý nội dung trên website.
Chúng tôi tách rõ nhu cầu nội dung khỏi yêu cầu bán hàng. Cách tách này ngăn đội ngũ kéo nhóm thanh toán vào một tác vụ chỉ liên quan bài viết. Nó cũng làm phạm vi thử nghiệm gọn hơn.
Các nhánh nghiệp vụ riêng
Affiliate là một nhánh riêng trong chín nhóm API. Từ này chỉ hoạt động giới thiệu để nhận hoa hồng. Khi luồng có nhánh ấy, đội kỹ thuật nên đọc đúng nhóm affiliate rồi mới nối với phần đơn hàng liên quan.
Phần vận hành dịch vụ lại có bộ câu hỏi khác. Đội ngũ có thể cần xem nhóm nâng cấp và bảng giá (SAAS), hóa đơn hoặc quản lý tên miền. Mỗi nhóm nên được đối chiếu độc lập với tài liệu, vì nền tảng còn có phần REST.
Kiểm tra webhook theo tài liệu
Đôi lúc hệ thống nhận thông tin sau khi một sự kiện xảy ra. Webhook là cách một hệ thống chủ động báo cho hệ thống khác về sự kiện đó. Bạn nên đọc thêm cách thiết kế API webhook cho live chat để hiểu cơ chế, rồi kiểm tra tài liệu trước khi áp dụng.
Đoạn trên chỉ giải thích webhook như một mô hình kỹ thuật phổ biến. Chúng tôi không mặc định dịch vụ nào của Mona.Academy cũng hỗ trợ cơ chế này. Chỉ tài liệu công khai mới là căn cứ để đội phát triển chọn cách kết nối.
Triển khai một luồng hẹp
Trong một dự án, chúng tôi ưu tiên hoàn thành một luồng hẹp trước. Luồng đó phải chỉ rõ nhóm API và giao thức đang dùng. Sau khi đường đi đã sáng, việc mở sang nhóm khác sẽ ít nhầm hơn.
Bạn cũng nên giữ bản ghi về các quyết định tích hợp. Một dòng ghi “GraphQL qua /graphql/” đã giúp người vào sau hiểu điểm bắt đầu. Với phần REST, hãy ghi đúng dịch vụ được tài liệu chỉ ra.
Mona.Academy cung cấp website bán khóa học riêng thương hiệu sau khi người dùng đăng ký. Website có tên miền riêng, nên người dùng không cần biết lập trình để bắt đầu. API phục vụ nhu cầu kết nối của đội kỹ thuật, không phải điều kiện để vận hành website.
Nếu đang chuẩn bị tích hợp API nền tảng khóa học, hãy chọn đúng một ca sử dụng rồi đối chiếu từng nhóm liên quan. Bắt đầu ở /graphql/ khi tài liệu dùng GraphQL, và chuyển sang REST tại phần được chỉ định. Cách đọc có mục tiêu luôn dễ kiểm soát hơn việc thử toàn bộ chín nhóm cùng lúc.