DİNLENME - kimlikleri vücuda koyun veya koymayın?

Diyelim ki, müşteriler için, müşterinin kimlik atayabileceği bir RESTful kaynağa sahip olmak istiyorum.

Bir kişi şuna benzer: {"id": <UUID>, "name": "Jimmy"}

Şimdi, müşteri bunu nasıl kaydetmeli (veya "PUT")?

1. PUT /person/UUID {"id": <UUID>, "name": "Jimmy"} - şimdi her zaman doğrulamamız gereken bu çirkin kopyaya sahibiz: Vücuttaki kimlik yoldakiyle eşleşiyor mu?
2. Asimetrik gösterim:
   • PUT /person/UUID {"name": "Jimmy"}
   • GET /person/UUID İadeler {"id": <UUID>, "name": "Jimmy"}
3. Gövdede kimlik yok - yalnızca konumda kimlik:
   • PUT /person/UUID {"name": "Jimmy"}
   • GET /person/UUID İadeler {"name": "Jimmy"}
4. POSTKimlik müşteri tarafından oluşturulduğu için hiçbir şey iyi bir fikir gibi görünmüyor.

Bunu çözmenin yaygın kalıpları ve yolları nelerdir? Yalnızca konumdaki kimlikler dogmatik olarak en doğru yol gibi görünse de, pratik uygulamayı da zorlaştırır.

Farklı okuma / yazma modellerine sahip olmanın yanlış bir tarafı yoktur: İstemci, bir kaynak gösterimini yazabilir, burada sunucu, eklenen / hesaplanan öğelerle başka bir gösterimi (veya hatta tamamen farklı bir temsili) geri döndürebilir (hatta tamamen farklı bir temsil - buna karşı herhangi bir özellik yoktur) , tek gereksinim, PUT'un kaynağı oluşturması veya değiştirmesidir).

Bu yüzden (2) 'deki asimetrik çözümü seçerim ve şunları yazarken sunucu tarafındaki "kötü çoğaltma kontrolünden" kaçınırdım:

PUT /person/UUID {"name": "Jimmy"}

GET /person/UUID returns {"id": <UUID>, "name": "Jimmy"}

Halka açık bir API ise, yanıt verirken muhafazakar olmalısınız, ancak serbestçe kabul etmelisiniz.

Bununla demek istediğim, hem 1 hem de 2'yi desteklemelisin. 3'ün mantıklı olmadığına katılıyorum.

Hem 1 hem de 2'yi desteklemenin yolu, istek gövdesinde hiçbiri sağlanmamışsa url'den kimliği almak ve istek gövdesindeyse url'deki kimlik ile eşleştiğini doğrulamaktır. İkisi eşleşmezse, 400 Kötü İstek yanıtı döndürün.

Bir kişi kaynağını döndürürken muhafazakar olun ve koymada isteğe bağlı olsa bile, kimliği her zaman json'a ekleyin.

Bu sorunun bir çözümü, biraz kafa karıştırıcı olan "Hypertext As The Engine of Application State" veya "HATEOAS" kavramını içeriyor. Bu, bir REST yanıtının mevcut kaynakları veya köprüler olarak gerçekleştirilecek eylemleri içerdiği anlamına gelir. Orijinal REST anlayışının bir parçası olan bu yöntemi kullanarak, kaynakların benzersiz tanımlayıcıları / kimliklerinin kendileri birer köprüdür. Yani, örneğin, aşağıdaki gibi bir şeye sahip olabilirsiniz:

GET /person/<UUID> {"person": {"location": "/person/<UUID>", "data": { "name": "Jimmy"}}}

Ardından, bu kaynağı güncellemek istiyorsanız şunları yapabilirsiniz (sözde kod):

updatedPerson = person.data
updatedPerson.name = "Timmy"
PUT(URI: response.resource, data: updatedPerson)

Bunun bir avantajı, istemcinin sunucunun Kullanıcı Kimliklerinin dahili temsili hakkında herhangi bir fikre sahip olmamasıdır. İstemcinin bunları keşfetme yolu olduğu sürece kimlikler değişebilir ve hatta URL'lerin kendisi de değişebilir. Örneğin, bir insan topluluğu alırken, şöyle bir yanıt döndürebilirsiniz:

GET /people
{ "people": [
    "/person/1",
    "/person/2"
  ]
}

(Tabii ki, başvurunun ihtiyaçlarına bağlı olarak her kişi için tam kişi nesnesini de iade edebilirsiniz).

Bu yöntemle nesnelerinizi daha çok kaynaklar ve konumlar açısından, daha az kimlik açısından düşünürsünüz. Benzersiz tanımlayıcının dahili temsili böylece istemci mantığınızdan ayrıştırılır. Bu, REST'in arkasındaki ilk itici güçtü: HTTP özelliklerini kullanarak, daha önce var olan RPC sistemlerinden daha gevşek bir şekilde bağlanmış istemci-sunucu mimarileri oluşturmak. HATEOAS hakkında daha fazla bilgi için Wikipedia makalesine ve bu kısa makaleye bakın .

Bir ekte, URL'ye kimliği eklemeniz gerekmez. Bu şekilde, bir PUT'ta bir kimlik gönderirseniz, birincil anahtarı değiştirmek için GÜNCELLEME olarak yorumlayabilirsiniz.

1. EKLEYİN:

   PUT /persons/ 
     {"id": 1, "name": "Jimmy"}
   HTTP/1.1 201 Created     
     {"id": 1, "name": "Jimmy", "other_field"="filled_by_server"}
   
   GET /persons/1
   
   HTTP/1.1 200 OK
     {"id": 1, "name": "Jimmy", "other_field"="filled_by_server"}  
   

2. GÜNCELLEME

   PUT /persons/1 
        {"id": "2", "name": "Jimmy Jr"} - 
   HTTP/1.1 200 OK
        {"id": "2", "name": "Jimmy Jr", "other_field"="filled_by_server"}
   
   GET /persons/2 
   
   HTTP/1.1 200 OK
        {"id": "2", "name": "Jimmy Jr", "other_field"="updated_by_server"}
   

JSON API bu standardı ve çözer yeni nesneye bir bağlantı ile eklenen veya güncellenen nesneyi dönen bazı sorunlar kullanır. Bazı güncellemeler veya ekler, ek alanları değiştirecek bazı iş mantığı içerebilir

Ekleme ve güncellemeden sonra alma işleminden kurtulabileceğinizi de göreceksiniz.

Bu daha önce sorulmuştu - tartışma bir göz atmaya değer:

RESTful GET yanıtı bir kaynağın kimliğini döndürmeli mi?

Bu, neyin "RESTful" olup olmadığına dair tartışmaya girmenin kolay olduğu sorulardan biridir .

Ne olursa olsun, tutarlı kaynaklar açısından düşünmeye çalışıyorum ve bunların tasarımını yöntemler arasında değiştirmemeye çalışıyorum. Bununla birlikte, IMHO, kullanılabilirlik açısından en önemli şey, tüm API'de tutarlı olmanızdır!

Farklı operasyonlar için farklı temsillere sahip olmak normal olsa da, PUT için genel bir öneri , BÜTÜN yükü içermektir . Bu, onun idda orada olması gerektiği anlamına gelir . Aksi takdirde, PATCH kullanmalısınız.

Bunu söyledikten sonra, PUT'un çoğunlukla güncellemeler için kullanılması idgerektiğini ve her zaman URL'de de iletilmesi gerektiğini düşünüyorum. Bunun sonucunda, kaynak tanımlayıcısını güncellemek için PUT kullanmak kötü bir fikirdir. idURL’de olandan farklı olabileceği zaman bizi istenmeyen bir durumda bırakır .id vücutta olandan .

Öyleyse, böyle bir çatışmayı nasıl çözeriz? Temelde 2 seçeneğimiz var:

• 4XX istisnası at
• bir Warning( X-API-Warnvb.) başlık ekleyin .

Bu soruyu cevaplamaya olabildiğince yakın çünkü konu genel olarak bir fikir meselesidir.

Farklı yaklaşımlar kullanmanın kötü bir yanı yoktur. ama bence en iyi yol 2. ile çözüm .

 PUT /person/UUID {"name": "Jimmy"}

 GET /person/UUID returns {"id": <UUID>, "name": "Jimmy"}

çoğunlukla bu şekilde kullanılır , varlık çerçevesi bile bu tekniği , varlık dbContext'e eklendiğinde, üretilen ID'siz sınıf, Entity Framework referans tarafından oluşturulan ID'dir.

Buna JSON-LD / Anlamsal Web açısından bakıyorum çünkü bu slaytlarda ana hatlarıyla belirttiğim gibi gerçek REST uyumluluğunu elde etmenin iyi bir yolu . Bu perspektiften bakıldığında, bir Web kaynağının ID'si (IRI) her zaman kaynağa bakmak / referansını kaldırmak için kullanabileceğim URL'ye eşit olması gerektiğinden, seçenek (1) için gidecek bir soru yoktur. Doğrulamanın uygulanmasının gerçekten zor olmadığını ve sayısal olarak yoğun olmadığını düşünüyorum; bu yüzden bunu seçenek (2) ile devam etmek için geçerli bir neden olarak görmüyorum. POST (yeni oluştur), PUT (güncelle / değiştir) 'den farklı bir semantiğe sahip olduğundan, seçenek (3.) gerçekten bir seçenek değildir.

Bilginize, buradaki cevaplar yanlış.

Görmek:

https://restfulapi.net/rest-api-design-tutorial-with-example/

https://restfulapi.net/rest-put-vs-post/

https://restfulapi.net/http-methods/#patch

KOYMAK

Öncelikle mevcut kaynağı güncellemek için PUT API'lerini kullanın (kaynak yoksa, API yeni bir kaynak oluşturmaya veya oluşturmamaya karar verebilir). PUT API tarafından yeni bir kaynak yaratılmışsa, kaynak sunucunun kullanıcı aracısını HTTP yanıt kodu 201 (Oluşturuldu) yanıtı ile bilgilendirmesi ZORUNLUdur ve mevcut bir kaynak değiştirilirse, 200 (Tamam) veya 204 (İçerik Yok) yanıt kodlarının, talebin başarıyla tamamlandığını belirtmek için gönderilmesi GEREKİR.

İstek bir önbellekten geçerse ve İstek-URI'si şu anda önbelleğe alınmış bir veya daha fazla varlığı tanımlarsa, bu girişler eski olarak işlem görmelidir. Bu yönteme verilen yanıtlar önbelleğe alınamaz.

Zaten kaynak koleksiyonunun bir parçası olan tekil bir kaynağı değiştirmek istediğinizde PUT kullanın. PUT, kaynağın tamamını değiştirir. İstek, kaynağın bir bölümünü güncellerse PATCH kullanın.

YAMA

HTTP PATCH istekleri, bir kaynakta kısmi güncelleme yapmak içindir. PUT isteklerinin de bir kaynak varlığını değiştirdiğini görürseniz, daha net hale getirmek için - PATCH yöntemi, mevcut bir kaynağı kısmen güncellemek için doğru seçimdir ve PUT yalnızca bir kaynağı tamamen değiştiriyorsanız kullanılmalıdır.

Yani onu şu şekilde kullanmalısınız:

POST    /device-management/devices      : Create a new device
PUT     /device-management/devices/{id} : Update the device information identified by "id"
PATCH   /device-management/devices/{id} : Partial-update the device information identified by "id"

RESTful uygulamaları, / {id} konumuna ne koyduğunuza dikkat etmelisiniz - kaydın içeriği, yük tarafından sağlanan içeriğe güncellenmelidir - ancak GET / {id} yine de aynı kaynağa bağlanmalıdır.

Başka bir deyişle, PUT / 3, yük kimliği 4 olarak güncellenebilir, ancak GET / 3 yine de aynı yüke bağlanmalıdır (ve kimliği 4 olarak ayarlanmış olanı döndürmelidir).

API'nizin URI ve yükte aynı tanımlayıcıyı gerektirdiğine karar verirseniz, eşleştiğinden emin olmak sizin işinizdir, ancak tümüyle orada olması gereken yükteki kimliği hariç tutuyorsanız kesinlikle PUT yerine PATCH kullanın. . Kabul edilen yanıtın yanlış olduğu yer burasıdır. PUT, tüm kaynağın yerini almalıdır, çünkü yama kısmi olabilir.

PATCH / PUT istek türlerine bakmanız gerekebilir.

PATCH istekleri bir kaynağı kısmen güncellemek için kullanılırken, PUT isteklerinde, tüm kaynağı sunucuda geçersiz kılınacağı yere göndermeniz gerekir.

Url'de bir kimlik olması söz konusu olduğunda, bir kaynağı tanımlamak için standart bir uygulama olduğu için her zaman sahip olmanız gerektiğini düşünüyorum. Stripe API bile bu şekilde çalışır.

Sunucudaki bir kaynağı kimliğini tanımlamak için güncellemek için bir PATCH isteği kullanabilirsiniz, ancak gerçek kimliği güncellemeyin.