ID thông tin và được tạo duy nhất trong REST API

Question

Thiết kế API RESTful. Tôi có hai cách để xác định tài nguyên (dữ liệu người). Hoặc bằng ID duy nhất được tạo bởi cơ sở dữ liệu hoặc bằng số an sinh xã hội (SSN), được nhập cho từng người. SSN được cho là duy nhất, mặc dù có thể thay đổi.

Sử dụng ID sẽ thuận tiện nhất cho tôi, vì nó được đảm bảo là duy nhất và không thay đổi. Do đó, URL cho tài nguyên, cũng luôn luôn giữ nguyên:

GET /persons/12 

{ 
    "name": Morgan 
    "ssn": "840212-3312" 
} 

Lý lẽ cho việc sử dụng SSN, là khách hàng API có nhiều thông tin và dễ hiểu hơn. SSN cũng được sử dụng nhiều trong các hệ thống xung quanh:

GET /persons/840212-3321 

{ 
    "name": Morgan 
    "id": "12" 
} 

Vì vậy, câu hỏi là: Tôi có nên đi với cách tiếp cận đầu tiên, và tránh được một số đau đầu thực hiện nơi SSN có thể thay đổi. Và có thể cung cấp một số phương thức trợ giúp chuyển đổi từ SSN thành ID?

Hoặc đi theo phương pháp thứ hai. Cung cấp API nhiều thông tin hơn. Mặc dù phải đối phó với một số khác biệt không yên tĩnh như vậy mà URL: s có thể thay đổi do thay đổi SSN?

Answer 1

Thiết kế URL là lựa chọn cá nhân. Nhưng để cung cấp cho bạn một số ví dụ khác với những gì Ray đã cung cấp, tôi sẽ cung cấp cho bạn một số ví dụ của riêng tôi.

Tôi có một nguồn lực tài khoản người dùng và cho phép truy cập qua cả URI:

/users/12 

và

/users/morgan 

trong đó giá trị số là một ID auto_incremented, và giá trị chữ cái là một tên người dùng duy nhất trên hệ thống được chỉ định bởi người dùng. các tài nguyên này không thể thực hiện được vì vậy tôi không bận tâm về việc hợp quy hóa, tuy nhiên, các liên kết trang /users liên kết với các biểu mẫu chữ cái.

Không có tài nguyên nào khác trên hệ thống của tôi có hai trường duy nhất, do đó được tham chiếu theo ID, /jobs/123, /quotations/456.

Như bạn thấy, tôi thích phân đoạn URI số nhiều hơn ;-)
Tôi nghĩ "công việc 123" là từ bộ sưu tập "công việc", vì vậy có vẻ hợp lý để có tài nguyên "công ăn việc làm" mỗi công việc.

Bạn không cần phải có một diện tích /search/ riêng cho thực hiện tìm kiếm, tôi nghĩ rằng nó sẽ sạch hơn để áp dụng tiêu chí tìm kiếm của bạn vào nguồn thu trực tiếp:

/people?ssn=123456-7890 (people with SSN matching/containing "123456-7890") 
/people?name=morgan  (people who's name is/contains "Morgan") 

Tôi có một cái gì đó tương tự, nhưng chỉ sử dụng chữ cái đầu tiên làm bộ lọc:

/sites?alpha=f 

Liệt kê tất cả các trang web bắt đầu bằng F. Bạn có thể coi đó là bộ lọc hoặc tiêu chí tìm kiếm, các từ này chỉ là các mặt khác nhau của cùng một đồng xu.

Answer 2

Tốt để xem ai đó dành thời gian suy nghĩ về url tài nguyên của họ!

Tôi sẽ tạo một Url có id duy nhất để cung cấp tài nguyên cho một người dùng. Giống như:

http://api.mysite.com/person/12/ 

Trường hợp 12 là ID duy nhất của bạn. Lưu ý rằng tôi cũng thích số ít 'người' ....

Bất kể, url sẽ trở lại:

{ 
    "ssn": "840212-3312" 
    "name": "Morgan" 
    "id": "12" 
} 

Tuy nhiên, tôi cũng sẽ tạo ra một URL tìm kiếm chung mà trả về một danh sách người dùng phù hợp các tham số (hoặc là một mảng json hoặc bất kỳ định dạng nào bạn cần). Bạn có thể chỉ định các thông số tìm kiếm như nhận params như thế này:

http://api.mysite.com/person/search/?ssn=840212-3312 

Hoặc

http://api.mysite.com/person/search/?name=Morgan 

Những sẽ quay trở lại một cái gì đó như thế này cho một hit tìm kiếm duy nhất - lưu ý đó là một mảng, không phải là một mục duy nhất như url id duy nhất trỏ trực tiếp tới một người dùng.

[{ 
    "ssn": "840212-3312" 
    "name": "Morgan" 
    "id": "12" 
}] 

Tìm kiếm này sau đó có thể được tăng cường thêm cho các tiêu chí tìm kiếm khác. Bạn chỉ có thể trả về id duy nhất thông qua Url tìm kiếm - bạn luôn có thể đưa ra yêu cầu tới url id duy nhất khi bạn đã nhận được yêu cầu đó từ tìm kiếm ...

Answer 3

Tôi khuyên bạn không nên sử dụng. Tạo ID tài nguyên duy nhất cho cả một người dùng API của bạn và trên tất cả các tài nguyên khác (bao gồm cả tài nguyên của người dùng khác).

Sử dụng ID cơ sở dữ liệu duy nhất không lý tưởng vì một vài lý do. Đầu tiên, các tài nguyên API và các bản ghi cơ sở dữ liệu sẽ không nhất thiết phải luôn luôn là 1-to-1 ngay cả khi bạn đã thiết kế nó theo cách đó ngày hôm nay. Thứ hai, bạn có thể thay đổi sang một kho dữ liệu khác có thể tạo ra các định dạng id duy nhất khác nhau. Ngoài ra, cách tốt nhất là tách ID ra khỏi các thuộc tính tài nguyên khác, chẳng hạn như SSN (như một phần sang một bên, tôi hy vọng bạn đang lưu trữ SSN một cách rất an toàn, nhưng đó là một chủ đề khác). Nếu vì lý do nào đó mà SSN đã thay đổi, nhiều hơn một tài nguyên API được liên kết với cùng một SSN hoặc bạn quyết định rằng một phần dữ liệu không cần thiết vào một ngày nào đó, bạn không muốn phải thay đổi ID.

Một mẫu là thêm ID duy nhất bằng một vài ký tự cho biết loại tài nguyên. Ví dụ: nếu Người dùng là một loại tài nguyên trong API của bạn, một ID duy nhất được tạo sẽ là một cái gì đó như USR56382.