GERİSİ hakkında bildiğimi sandığım şeyler büyük miktarda ki yanlış ve yalnız değilim. Bu soru bir uzun yol var, ama bu bilgiler biraz dağınık olduğu için gerekli gibi görünüyor. Asıl soru zaten bu konu hakkında bilginiz varsa sonunda gelir.

Roy Fielding ilk paragraftan REST APIs must be hypertext-driven, işini çok yanlış ediliyor inandığı çok açık

İnsanlar HTTP tabanlı REST API arayüzü herhangi bir arama sayısı ile sinirli alıyorum. Bugünün örnek SocialSite REST API. RPC. RPC diye bağırıyor. X bir not verilmesi gerektiğini ekranda çok denge var.

Fielding bir DİNLENME çeşitli öznitelikleri API liste uzayıp gidiyor. Bazıları ÇOK yaygın bir uygulama ve ortak DANIŞMANLIK ve diğer forumlar karşı gitmek gibi görünüyor. Örneğin:

• Bir REST API girilmelidir, hiçbir ön bilgi dışında ilk URİ (bookmark) ve set standart medya türleri uygun hedef kitlesi (yani, beklenen anlaşılan herhangi bir istemci bu olabilir kullanın API). ...

• REST API sabit kaynak adları veya hiyerarşileri (istemci ve sunucu bariz bir kaplin) tanımlamak gerekir. ...

• Bir REST API gereken harcama neredeyse tüm açıklayıcı çaba belirleyici ortam türü(ler) için kullanılan kaynakları temsil eden ve sürüş uygulama durumu, ya da tanımlayan genişletilmiş ilgili isim ve/veya köprü metni etkin bir mark-up için mevcut standart kağıt türleri. ...

"Merkezi bir rol fazla URİ yapısı daha oynar ya da fiil ne demek HTTP. "köprü fikri "Köprü" yorumlardan biri olarak tanımlanır:

Ben [Fielding] köprü dediğimiz zaman, bilgi gibi bu bilgi ve denetimleri aynı anda sunum üzerinden kullanıcı (otomat) seçimleri alır ve eylemleri seçer program olur. Hiper metin medya akışı içinde zamansal çapa eklemek için ne anlama geldiğini sadece bir genişleme; çoğu araştırmacılar ayrım düştü.

Köprü metni bir tarayıcı üzerinde HTML olması gerekmez. Makine veri biçimi ve ilişki türleri anladıklarında linkleri takip edebilirsiniz.

Sanırım bu noktada, ama ilk iki puan yukarıda görünmek önermek API belgelerine Foo kaynak şeye benzeyen aşağıdaki yol için sıkı kavrama arasında istemci ve sunucu ve hiçbir yerde Dinlendirici bir sistem.

GET   /foos/{id}  # read a Foo
POST  /foos/{id}  # create a Foo
PUT   /foos/{id}  # update a Foo

Bunun yerine, bir ajan tüm Foos için bu Kodu bulmak için, örneğin, a /foos karşı istek OLSUN yayımlayarak zorlanacak. (Bu Konudaki desen izleyin çıkmak olabilir, ama konumuz bu değil.) Yanıt her öğeye erişmek için nasıl ve neler yapılabileceğini taşıma kapasitesine sahip bir medya türü, üçüncü nokta sebebiyet veren yukarıda kullanır. Bu nedenle, API belgelerine köprü yanıt içerdiği yorumlamak için nasıl açıklayan odaklanmak gerekir.

Ayrıca, her zaman bir URI için bir Foo kaynak talep etmesine tepki içeren tüm gerekli bilgiler için bir ajan için nasıl keşfetmek için devam, örneğin, erişim ilişkili ve üst kaynakları ile kendi URI veya alarak eylemden sonra oluşturma/Silme bir kaynak.

Tüm sistem anahtarı yanıt geçmeden aracı seçenekleri için kendisini nakleden bir köprü metni bir ortam türü bilgiler içerir. Bir tarayıcı insanlar için çalışır şekilde farklı değil.

Ama bu şu anda en iyi tahminim sadece.

Fielding onun tartışması çok soyut olduğunu eleştiri, örnekler eksik yanıtladı follow-up ve jargon-zengin gönderildi

Diğerleri daha doğrudan ya da bugün bazı pratik endişe geçerli bir şekilde yazdım çözmeye çalışacağız. Muhtemelen olmaz, çünkü ben çok meşgul filika ile bir sonraki konu, hazırlanması için bir konferans, yazı başka bir standart, seyahat için uzak bir yere, ya da sadece küçük şeyler ver bana hissediyorum Ben kazandım maaşımı.

Bu yüzden, geri KALAN iki basit soru orada pratik bir zihniyetle uzmanlar: nasıl Fielding söylediklerini nasıl yorumluyorsunuz ve nasıl/uygulama REST API belgeleme uygulamaya koydu mu?

Edit: bu soru ne kadar zor olursa neden bahsettiğini için bir adı yok eğer bir şey öğrenmek olabilir bir örnektir. Bu durumda ismi "Uygulama Durumu Motoru olarak Hiper ortam" (HATEOAS).

Açıklama çoğunlukla anlatmaya yeter. URI, çoğunlukla, kullanıcı Aracısı tarafından uygulamaya erişmek için kullanılan yer işareti URİ ötesinde tebliğ edilmemesi gerektiğini opak tanımlayıcıları vardır.

Belgelemeye gelince, bu soru pek çok kez yapıldı. Ortam türü, bir arada bulunduğu köprü denetimleri (bağlantılar ve form) ve eğer isterseniz etkileşim modeli (bkz AtomPub) belge.

Sen nasıl bu Kodu belge ya da eğer, yanlış yapıyorsun.