REST URI kuralı - Oluştururken kaynağın tekil veya çoğul adı

REST'te yeniyim ve bazı RESTful hizmetlerinde güncelleme / alma / silme ve Oluşturma için farklı kaynak URI kullandıklarını gözlemledim. Gibi

• Oluşturmak - kullanan / kaynaklar kullanarak bazı yerlerde POST yöntemi (çoğul dikkat edin) ile / kaynak (tekil)
• Güncelleme - PUT yöntemiyle / resource / 123 kullanma
• Get - GET yöntemiyle / resource / 123 kullanma

Bu URI adlandırma kuralı hakkında biraz kafam karıştı. Kaynak oluşturmak için çoğul veya tekil ne kullanmalıyız? Buna karar verirken kriterler ne olmalı?

Kullanmanın temeli, /resources"tüm" kaynakları temsil etmesidir. Bir yaparsanız GET /resources, büyük olasılıkla tüm koleksiyonu döndürürsünüz. Adresine POST yaparak /resources, koleksiyona ekliyorsunuz.

Ancak, bireysel kaynaklar / resource adresinde bulunabilir. Bunu yaparsanız GET /resource, büyük olasılıkla hata yaparsınız , çünkü bu istek bir anlam ifade etmiyor, oysa /resource/123mükemmel bir anlam ifade ediyor.

Kullanma /resourceyerine /resourcessen söz hakkından, bir dosya sistemi ve dosyalar koleksiyonu, çalışmak ve sanki bunu nasıl benzer /resourcebireysel ile "dizin" dır 123, 456o dosyalara.

Her iki şekilde de doğru ya da yanlış, en çok sevdiğiniz şeyle gidin.

Benim için doğrudan kodla eşleştirebileceğiniz (otomatikleştirilmesi kolay) bir şemaya sahip olmak daha iyidir, çünkü kod her iki uçta da olacak.

GET  /orders          <---> orders 
POST /orders          <---> orders.push(data)
GET  /orders/1        <---> orders[1]
PUT  /orders/1        <---> orders[1] = data
GET  /orders/1/lines  <---> orders[1].lines
POST /orders/1/lines  <---> orders[1].lines.push(data) 

Bunu da yapmanın nedenini görmüyorum ve bunun en iyi URI tasarımı olmadığını düşünüyorum. RESTful hizmetinin bir kullanıcısı olarak, listeye veya listede 'belirli' kaynağa erişiyor olsam da liste kaynağının aynı ada sahip olmasını beklerdim. Liste kaynağını veya belirli bir kaynağı kullanmak isteyip istemediğinize bakmaksızın aynı tanımlayıcıları kullanmalısınız.

Çoğul

• Basit - tüm URL'ler aynı önekle başlar
• Mantıksal - orders/siparişlerin bir dizin listesini alır.
• Standart - En yaygın kabul gören standart ve bunu takiben genel ve özel API'lerin büyük çoğunluğu.

Örneğin:

GET /resources - kaynak öğelerinin bir listesini döndürür

POST /resources - bir veya daha fazla kaynak öğesi oluşturur

PUT /resources - bir veya daha fazla kaynak öğesini günceller

PATCH /resources - bir veya daha fazla kaynak öğesini kısmen günceller

DELETE /resources - tüm kaynak öğelerini siler

Ve tek kaynak öğeleri için:

GET /resources/:id- :idparametreye dayalı olarak belirli bir kaynak öğe döndürür

POST /resources/:id - belirtilen kimliğe sahip bir kaynak öğesi oluşturur (doğrulama gerektirir)

PUT /resources/:id - belirli bir kaynak öğeyi günceller

PATCH /resources/:id - belirli bir kaynak öğeyi kısmen günceller

DELETE /resources/:id - belirli bir kaynak öğeyi siler

Tekil savunucuları için şunu düşünün: Birinden orderbir şey ister ve bir şey mi yoksa bir şeyler listesi mi beklerdiniz? Öyleyse neden bir servisin yazarken bir şeyler listesi döndürmesini beklersiniz /order?

Tekil

Kolaylık Şeyler düzensiz çoğul isimlere sahip olabilir. Bazen bir tane olmaz. Ancak Singular isimleri her zaman oradadır.

örneğin, Müşteri Adresleri Üzerinden Müşteri Adresi

Bu ilgili kaynağı düşünün.

Bu /order/12/orderdetail/12daha okunabilir ve mantıklı /orders/12/orderdetails/4.

Veritabanı Tabloları

Kaynak, veritabanı tablosu gibi bir varlığı temsil eder. Mantıksal tekil bir adı olmalıdır. İşte tablo isimleri üzerine cevap .

Sınıf Eşleme

Sınıflar daima tekildir. ORM araçları, sınıf adlarıyla aynı adlara sahip tablolar oluşturur. Giderek daha fazla araç kullanıldıkça, tekil isimler bir standart haline geliyor.

A REST API Developer's Dilemma hakkında devamını oku

En yaygın uygulama, çoğulların kullanıldığı RESTful apis iken, /api/resources/123tekil bir ismin kullanımını çoğul isimlerden daha uygun / ifade edici bulduğum özel bir durum vardır. Birebir ilişkiler söz konusudur. Özellikle, hedef öğe bir değer nesnesiyse (Etki alanına dayalı tasarım paradigmasında).

Her kaynağın accessLogbir varlık nesnesi olarak modellenebilecek bire bir olduğunu varsayalım . Olarak ifade edilebilir /api/resources/123/accessLog. Her zamanki fiiller (POST, PUT, DELETE, GET), niyetin ve ilişkinin gerçekten birebir olduğu gerçeğini uygun bir şekilde ifade eder.

Neden tekil bir formun genel olarak kabul edildiği veritabanı tablosu adlarının yaygın eğilimini takip etmiyorsunuz? Orada bulundum, bunu yapalım - yeniden kullanalım.

Tablo Adlandırma İkilemi: Tekil ve Çoğul İsimler

Bu kadar çok insanın çoğul isim bandwagonuna atlayacağını görmek beni şaşırttı. Tekil çoğul dönüşümleri uygularken, düzensiz çoğul isimlerle ilgileniyor musunuz? Acıdan hoşlanıyor musunuz?

Bkz. Http://web2.uvcs.uvic.ca/elc/studyzone/330/grammar/irrplu.htm

Birçok düzensiz çoğul türü vardır, ancak bunlar en yaygın olanlarıdır:

İsim türü Çoğul oluşturma

Ends with -fe   Change f to v then Add -s   
    knife   knives 
    life   lives 
    wife   wives
Ends with -f    Change f to v then Add -es  
    half   halves 
    wolf   wolves
    loaf   loaves
Ends with -o    Add -es 
    potato   potatoes
    tomato   tomatoes
    volcano   volcanoes
Ends with -us   Change -us to -i    
    cactus   cacti
    nucleus   nuclei
    focus   foci
Ends with -is   Change -is to -es   
    analysis   analyses
    crisis   crises
    thesis   theses
Ends with -on   Change -on to -a    
    phenomenon   phenomena
    criterion   criteria
ALL KINDS   Change the vowel or Change the word or Add a different ending   
     man   men
     foot   feet
     child   children
     person   people
     tooth   teeth
     mouse   mice
 Unchanging Singular and plural are the same    
     sheep deer fish (sometimes)

API tüketicisinin bakış açısından, uç noktalar öngörülebilir olmalıdır.

İdeal ...

1. GET /resources bir kaynak listesi döndürmelidir.
2. GET /resource 400 düzeyli bir durum kodu döndürmelidir.
3. GET /resources/id/{resourceId} bir kaynağı tek bir koleksiyonla döndürmelidir.
4. GET /resource/id/{resourceId} bir kaynak nesnesi döndürmelidir.
5. POST /resources toplu iş kaynakları oluşturmalıdır.
6. POST /resource kaynak yaratmalı.
7. PUT /resource bir kaynak nesnesini güncellemelidir.
8. PATCH /resource yalnızca değiştirilen özellikleri göndererek bir kaynağı güncellemelidir.
9. PATCH /resources yalnızca değişen öznitelikleri göndererek toplu güncelleme kaynaklarını kullanmalıdır.
10. DELETE /resourcestüm kaynakları silmeli; şaka yapıyorum: 400 durum kodu
11. DELETE /resource/id/{resourceId}

Bu yaklaşım, en esnek ve zengin özelliklere sahip olmakla birlikte, aynı zamanda geliştirilmesi için en fazla zaman alan yöntemdir. Eğer aceleniz varsa (ki bu her zaman yazılım geliştirme için geçerlidir) sadece bitiş noktanızı resourceveya çoğul halinizi belirtin resources. Tekil formu tercih ederim, çünkü tüm çoğul formlar 's' ile bitmediği için programlı olarak introspekt ve değerlendirme seçeneği sunar.

Tüm bunları söyledikten sonra, en yaygın kullanılan uygulama geliştiricisinin seçtiği sebep ne olursa olsun çoğul formu kullanmaktır. Bu sonuçta seçtiğim rotadır ve popüler apislere bakarsanız githubve twitteryaptıkları budur.

Karar vermek için bazı kriterler şunlar olabilir:

1. Zaman kısıtlamalarım nelerdir?
2. Tüketicilerimin hangi işlemleri yapmasına izin vereceğim?
3. Talep ve sonuç yükü neye benziyor?
4. Kodumda yansıma kullanabilmek ve URI'yi ayrıştırmak ister miyim?

Yani size kalmış. Ne yaparsanız yapın tutarlı olun.

İki sentim: zamanlarını çoğuldan tekil veya viceversa değiştirerek geçiren yöntemler CPU döngüleri israfıdır. Eski okul olabilirim, ama zamanımda işler aynı şekilde adlandırıldı. İnsanlarla ilgili yöntemleri nasıl ararım? Hiçbir düzenli ifade, istenmeyen yan etkileri olmayan kişileri ve insanları kapsamaz.

İngilizce çoğullar çok keyfi olabilir ve kodu gereksiz yere tıkarlar. Bir adlandırma kuralına sadık kalın. Bilgisayar dillerinin doğal dili taklit etmekle değil, matematiksel netlikle ilgili olması gerekiyordu.

Hem basitlik hem de tutarlılık için tekil form kullanmayı tercih ederim.

Örneğin, aşağıdaki url dikkate alınarak:

/ Müşteri / 1

Müşteriye müşteri koleksiyonu olarak davranacağım, ancak basitlik için koleksiyon kısmı kaldırıldı.

Başka bir örnek:

/ Ekipman / 1

Bu durumda, ekipmanlar doğru çoğul form değildir. Bu nedenle, bir ekipman koleksiyonu olarak ele alınması ve basitlik için koleksiyonu kaldırması, müşteri durumu ile tutarlı olmasını sağlar.

Bir rotadaki kimlik, bir listenin dizini ile aynı şekilde görüntülenmeli ve adlandırma buna göre devam etmelidir.

numbers = [1, 2, 3]

numbers            GET /numbers
numbers[1]         GET /numbers/1
numbers.push(4)    POST /numbers
numbers[1] = 23    UPDATE /numbers/1

Ancak bazı kaynaklar yollarında kimlikleri kullanmaz, çünkü yalnızca bir tane vardır veya bir kullanıcının asla birden fazlasına erişimi yoktur, bu nedenle bunlar listelenmez:

GET /dashboard
DELETE /session
POST /login
GET /users/{:id}/profile
UPDATE /users/{:id}/profile

Adlandırma kurallarıyla, "sadece birini seçip ona sadık kalın" demek genellikle güvenlidir, bu da mantıklıdır.

Bununla birlikte, REST'i birçok kişiye açıklamak zorunda kaldıktan sonra, uç noktaları bir dosya sistemindeki yollar olarak temsil etmek , bunu yapmanın en etkileyici yoludur.
Vatansız (dosyalar var ya da yok), hiyerarşik, basit ve tanıdık - yerel veya http yoluyla statik dosyalara nasıl erişeceğinizi zaten biliyorsunuz.

Ve bu bağlamda, dilbilimsel kurallar sizi yalnızca aşağıdakilere kadar ulaştırabilir:

Bir dizin birden fazla dosya ve / veya alt dizin içerebilir ve bu nedenle adı çoğul biçimde olmalıdır .

Ve bundan hoşlandım.
Öte yandan - bu sizin dizininiz, istediğiniz gibi ise "a-resource-or-multip-resources" olarak adlandırabilirsiniz. Bu gerçekten önemli bir şey değil.

Önemli olan, "resourceS" adlı bir dizinin altına "123" adlı bir dosya koyarsanız (bunun sonucunda /resourceS/123), dosyaya erişilebilir olmasını bekleyemezsiniz /resource/123.

O anda olması gerekenden daha akıllı yapmaya çalışmayın - şu anda erişmekte olduğunuz kaynak sayısına bağlı olarak çoğuldan singluar'a geçmek bazılarına estetik olarak hoş gelebilir, ancak etkili değildir ve bir sıradüzensel sistem.

Not: Teknik olarak, "sembolik bağlantılar" oluşturabilirsiniz, böylece /resources/123buna da erişilebilir /resource/123, ancak eski hala var olmalıdır!

Göz at Google 'ın Kaynak Adları: API Tasarım Rehberi adlandırma kaynaklardaki başka üstlenmek için.

Kısacası:

• Koleksiyonlar çoğul adlarla adlandırılır.
• Bireysel kaynaklar bir dize ile adlandırılır.

|--------------------------+---------------+-------------------+---------------+--------------|
| API Service Name         | Collection ID | Resource ID       | Collection ID | Resource ID  |
|--------------------------+---------------+-------------------+---------------+--------------|
| //mail.googleapis.com    | /users        | /name@example.com | /settings     | /customFrom  |
| //storage.googleapis.com | /buckets      | /bucket-id        | /objects      | /object-id   |
|--------------------------+---------------+-------------------+---------------+--------------|

Bu konuyu düşünürseniz okumaya değer.

Tüm yöntemler için çoğul kullanımı en azından bir açıdan daha pratiktir: Postman (veya benzer bir araç) kullanarak bir kaynak API'sı geliştirip test ediyorsanız, GET'ten PUT'a ve POST'a geçiş yaparken URI'yi düzenlemeniz gerekmez. .

Her iki gösterim de yararlıdır. Kolaylık için oldukça uzun bir süre tekil kullanmıştım, bükülme zor olabilir. Kesinlikle tekil REST API'leri geliştirme deneyimim, uç noktayı tüketen geliştiriciler, sonucun şeklinin ne olacağından emin değiller. Şimdi cevabın şeklini en iyi tanımlayan terimi kullanmayı tercih ediyorum.

Tüm kaynaklarınız üst düzey ise, tekil temsillerden kurtulabilirsiniz. Bükülmeden kaçınmak büyük bir kazançtır.

İlişkilerle ilgili sorguları temsil etmek için herhangi bir derin bağlantı yapıyorsanız, API'nıza karşı yazan geliştiricilere daha katı bir kongre yapılarak yardımcı olabilirsiniz.

Benim kuralım, bir URI'deki her derinlik düzeyinin ana kaynakla bir etkileşimi tanımlaması ve tam URI'nin neyin alındığını örtük olarak tanımlaması gerektiğidir.

Aşağıdaki modele sahip olduğumuzu varsayalım.

interface User {
    <string>id;
    <Friend[]>friends;
    <Manager>user;
}

interface Friend {
    <string>id;
    <User>user;
    ...<<friendship specific props>>
}

Bir istemcinin belirli bir kullanıcının belirli bir arkadaşının yöneticisini almasına izin veren bir kaynak sağlamanız gerekirse, şöyle görünebilir:

GET /users/{id}/friends/{friendId}/manager

Aşağıda bazı örnekler verilmiştir:

• GET /users - küresel kullanıcı koleksiyonundaki kullanıcı kaynaklarını listeleyin
• POST /users - global kullanıcılar koleksiyonunda yeni bir kullanıcı oluşturun
• GET /users/{id} - küresel kullanıcı koleksiyonundan belirli bir kullanıcıyı alma
• GET /users/{id}/manager - belirli bir kullanıcının yöneticisini edinin
• GET /users/{id}/friends - bir kullanıcının arkadaşlarının listesini al
• GET /users/{id}/friends/{friendId} - bir kullanıcının belirli bir arkadaşını edinin
• LINK /users/{id}/friends - bu kullanıcıya arkadaşlık ilişkisi ekle
• UNLINK /users/{id}/friends - bu kullanıcıdan bir arkadaş ilişkilendirmesini kaldır

Her seviyenin, üzerinde işlem yapılabilecek bir ebeveyne nasıl eşlendiğine dikkat edin. Aynı nesne için farklı ebeveynlerin kullanılması mantıksızdır. Adresinde bir kaynağın geri getirilmesi, GET /resource/123yeni bir kaynak oluşturmanınPOST /resources

Çoğu insanın çoğul mu yoksa tekil mi kullanacağına karar vermek arasında olduğunu biliyorum. Burada ele alınmayan sorun, müşterinin hangisini kullandığınızı bilmesi gerekeceğidir ve her zaman bir hata yapma olasılığı vardır. Benim önerim buradan geliyor.

Her ikisine de ne dersiniz? Böylece, tüm API'nız için tekil kullanın ve daha sonra çoğul biçimde yapılan istekleri tekil forma iletmek için yollar oluşturun. Örneğin:

GET  /resources     =     GET  /resource
GET  /resources/1   =     GET  /resource/1
POST /resources/1   =     POST /resource/1
...

Resmi aldınız. Kimse yanlış değil, minimum çaba ve müşteri her zaman doğru olacaktır.

{id}URL'lerin bir kısmının alt kaynaklarla örtüştüğünü görmek istemiyorum , çünkü idteorik olarak herhangi bir şey olabilir ve belirsizlik olacaktır. Farklı kavramları (tanımlayıcılar ve alt kaynak adları) karıştırmaktadır.

Benzer sorunlar genellikle görülen enumklasörleri olduğunda, sabitler veya farklı kavramlar (karma örnek içindir yapılar, klasör Tigers, Lionsve Cheetahs, ardından da adlandırılan bir klasör Animalsaynı düzeyde - Bir bir alt kümesidir olarak bu hiç mantıklı diğer).

Genel olarak, bir uç noktanın son adlandırılan kısmının, tek seferde tek bir varlık ile ilgiliyse tekil ve varlıkların bir listesi ile ilgiliyse çoğul olması gerektiğini düşünüyorum.

Tek bir kullanıcıyla ilgilenen uç noktalar:

GET  /user             -> Not allowed, 400
GET  /user/{id}        -> Returns user with given id
POST /user             -> Creates a new user
PUT  /user/{id}        -> Updates user with given id
DELETE /user/{id}      -> Deletes user with given id

Ardından, genellikle bir liste döndüren kullanıcılarda sorgulama yapmak için ayrı bir kaynak vardır:

GET /users             -> Lists all users, optionally filtered by way of parameters
GET /users/new?since=x -> Gets all users that are new since a specific time
GET /users/top?max=x   -> Gets top X active users

Ve burada belirli bir kullanıcıyla ilgilenen bir alt kaynak örnekleri:

GET /user/{id}/friends -> Returns a list of friends of given user

Arkadaş edin (çoktan çoka bağlantı):

PUT /user/{id}/friend/{id}     -> Befriends two users
DELETE /user/{id}/friend/{id}  -> Unfriends two users
GET /user/{id}/friend/{id}     -> Gets status of friendship between two users

Asla herhangi bir belirsizlik yoktur ve kaynağın çoğul ya da tekil isimlendirilmesi kullanıcıya ne bekleyebileceğine dair bir ipucudur (liste ya da nesne). idTeorik olarak new(potansiyel gelecek) alt kaynak adıyla örtüşmeden kimliğe sahip bir kullanıcıya sahip olmayı mümkün kılan s üzerinde herhangi bir kısıtlama yoktur .

Singular'ı kullanın ve örneğin "Ticaret Rehberi" nde görülen İngilizce sözleşmesinden yararlanın.

Birçok şey bu şekilde okur: "Kitap Çantası", "Köpek Paketi", "Sanat Galerisi", "Film Festivali", "Araba Lotu" vb.

Bu, soldan sağa doğru url yoluna uygundur. Soldaki öğe türü. Türü sağda ayarlayın.

Does GET /usersgerçekten hiç bir kullanıcı grubu getir? Genellikle değil. Bir anahtar ve belki de bir kullanıcı adı içeren bir dizi taslak getirir. Yani gerçekten /usersde değil . Bu bir kullanıcı dizini veya isterseniz bir "kullanıcı dizini" dir. Neden böyle demiyorsun? Bu bir /user/index. Küme türünü adlandırdığımızdan, örneğin user/phone-listveya sorgu parametrelerine başvurmadan bir kullanıcının farklı projeksiyonlarını gösteren birden çok türe sahip olabiliriz /user/mailing-list.

Peki ya Kullanıcı 300? Hala /user/300.

GET /user/index
GET /user/{id}

POST /user
PUT /user/{id}

DELETE /user/{id}

Kapanışta, HTTP tek bir isteğe yalnızca tek bir yanıt verebilir. Bir yol her zaman tekil bir şeyi ifade eder.

Benim için çoğullar koleksiyonu , tekiller ise bu koleksiyonun içindeki öğeleri manipüle ederler .

Koleksiyon , GET / POST / DELETE yöntemlerine izin verir

Öğe GET / PUT / DELETE yöntemlerine izin verir

Örneğin

POST / öğrenciler okula yeni bir öğrenci ekleyecek.

/ DELETE / öğrenciler okuldaki tüm öğrencileri kaldıracak.

/ Öğrenci / 123 üzerindeki SİL, öğrenci 123'ü okuldan kaldıracak.

Önemsiz gibi gelebilir, ancak bazı mühendisler bazen kimliği unutur. Rota her zaman çoğulsa ve bir DELETE gerçekleştirdiyse, verilerinizi yanlışlıkla silebilirsiniz. Oysa tekil kimlikte eksik ise 404 bulunamadı.

API'nın birden fazla okulu ortaya çıkarması gerekiyorsa örneği daha da genişletmek için,

/ Okul / abc / öğrencilerden SİL, okuldaki tüm öğrencileri kaldıracaktır abc.

Doğru kelimeyi seçmek bazen kendi başına bir zorluktur, ancak koleksiyon için çoğulluğu sürdürmeyi seviyorum. Örneğin, cart_itemsya da cart/itemsdoğru geliyor. Buna karşılık silme işlemi cart, sepet nesnesini değil, kendisinin sepet nesnesini siler;).

Nasıl olur:

/resource/(değil /resource)

/resource/ "kaynak" adı verilen bir klasör olduğu, "kaynak" klasörü olduğu anlamına gelir.

Ve ayrıca veritabanı tablolarının adlandırma kuralı aynı olduğunu düşünüyorum, örneğin, 'kullanıcı' adlı bir tablo bir "kullanıcı tablosu", "kullanıcı" adlı bir şey içeriyor.

Hem çoğul ( /resources) hem de tekil (/resource/{id} çünkü kaynakların toplanması üzerinde çalışmak ve tek bir kaynak üzerinde çalışmak arasındaki mantığı daha açık bir şekilde ayırdığını düşünüyorum.

Bunun önemli bir yan etkisi olarak, birisinin API'yi yanlış kullanmasını önlemeye de yardımcı olabilir. Örneğin, bir kullanıcının kimliği Id gibi bir parametre olarak belirterek yanlış bir şekilde kaynak almaya çalıştığı durumu düşünün:

GET /resources?Id=123

Bu durumda, çoğul sürümü kullandığımızda, sunucu büyük olasılıkla Id parametresini yok sayar ve tüm kaynakların listesini döndürür. Kullanıcı dikkatli değilse, aramanın başarılı olduğunu düşünecek ve listedeki ilk kaynağı kullanacaktır.

Öte yandan, tekil formu kullanırken:

GET /resource?Id=123

Kimlik doğru şekilde belirtilmediğinden ve büyük olasılıkla kullanıcının bir şeylerin yanlış olduğunu fark etmesi gerekecektir.