Bir mantık kontrol ihtiyacı - özel API Bina

6 Cevap php

Ben planlama ve büyük ölçekli biz uygulama için benim ilk tam teşekküllü API yazma erken kodlama aşamalarında duyuyorum. Ben yılda birkaç API'lerini kullanmış ama bu ben bu seviyede programlı etkileşimi sağlayacak bir şey inşa etmek istendi ilk kez.

Ben en iyi uygulamalar ve bu tür arayan araştırma yeraldığını yaptık ve ben oldukça esnek tepki haberleşme sistemi sunacak DÜŞÜN ne belirledik.

Benim sorular şunlardır:

Bu API etkileşim olarak görmek için ne bekliyoruz?

Ben önemli bir şey mi kaçırdım?

API Açıklama:

Ben iletişim ve kimlik doğrulama için benzersiz bir API anahtarı için HTTP Tip 1 protokolünü kullanıyor gidiyorum.

Ben bu bir SSL bağlantısı üzerinden CURL istekleri yoluyla gelmek bekliyorum.

Başarılı Örnek (200 OK) XML Tepki (hız limiti istek):

<?xml version="1.0" encoding="UTF-8"?>
<node>
    <short_message>Request Complete</short_message>
    <long_message>Rate Limit Status Response</long_message>
    <response_data>
        <rate_limit>40</rate_limit>
        <rate_used>31</rate_used>
    </response_data>
</node>

Başarısız XML Tepki örneği (uygun 400/500 Soket altında gönderilir olacak);

<?xml version="1.0" encoding="UTF-8"?>
<node>
    <error_code>1201</error_code>
    <short_message>API Error</short_message>
    <long_message>The requested API version (1.5) is invalid</long_message> 
</node>

Ayrıca ben diğer geliştiricilerin migren hafifletilmesi için arama mümkün belgelerinde kullanılacak hata kodları kuruyorum. Pass / istek Fail uygun HTTP kodları ile verilecektir - Başarı (200), kötü istekleri (400), yöntem (404) bulunamadı, kimlik vb (403) başarısız oldu ..

Herhangi bir kod değişiklikler dış kod değişiklikleri gerekmez böylece ben de sürüm tabanlı uç noktaları kullanıyorum.

Nihayet Devs XML, JSON, veya PHP tefrika diziler ya tüm yanıtları istemek mümkün olacak.

Benim kod iç yapıları çok basit. Tüm veriler benzersiz bir API anahtarı dahil (muhtemelen CURL ya da bazı alternatif kullanarak) POST geçirilir. Bu API anahtarı daha sonra iç yöntemleri belirli kullanıcı için etkin olan fonksiyonları bir dizi sınırlı yürütmesine olanak sağlayacak sistemde bir kullanıcı bağlantılıdır.

Ben Altın Rule' 'API takip ediyorum - "Her silmek asla eklemek".

Yani .. Ben başka ne düşünmeliyim ve ben ne kaçırdım?

6 Cevap

Shane

Ben Amacınız dinlendirici bir API oluşturmak olduğunu varsayarak kulüpler - doğrudur?

Benim cevabım bu varsayım doğruysa, yalnızca geçerlidir - Ben sadece kendi saldırganlık, tasarım eleştirmek için çalışıyorum değilim.

DİNLENME tasarım huzurlu olması için uyması gereken 4 arayüz kısıtlamaları tanımlar. Sizin tasarım onlara en az üç ihlal ve dolayısıyla huzurlu değildir. Bu başlı başına mutlaka kötü bir şey değil ama sizin sistem muhtemelen bunu olmasını bekliyoruz özelliklere sahip olmayacağını anlamak önemlidir.

Ben aşağıda kısa bir cevap ile başlamak için çalışıyorum, ama bir göz atın lütfen olacak http://nordsc.com/ext/classification_of_http_based_apis.html Ben biraz daha bu konuyu tartışmak nerede. Daha sonra muhtemelen küçük soruların tüm bu yıkmak ve buraya geri gelmek veya Yahoo gruplar üzerindeki dinlenme-tartışmak ziyaret edebilirsiniz: http://tech.groups.yahoo.com/group/rest-discuss/

Sizin tasarım Şimdi kısa yorumlar:

  1. Kendi yanıt kodlarını kullanabilirsiniz, ancak sadece HTTP tarafından sağlanan olanları kullanmak gerekir. Kendi olanları makyaj olabilir, ancak bu sizin uygulama veya etkileşim özgü olması genellikle geçerli ve olmamalıdır.

  2. Belirli bir ortam türü, uygulama / xml sadece kullanmalısınız. Mevcut türlerinden hiçbirinin gerek maç (ya da bunu yapmak için uzatılabilir) ise, kendi gelişebilir. Aslında, büyük tasarım etkinliği ortam türüne harcamak gerekir. Etki alanı semantik yaşadığı yerdir.

  3. Eğer gerçekten dinlendirici olması hipermedya kısıtlama uymalıdır. Bu istemci sonraki neler yapabileceğini keşfetmek bağlantılar ve / veya formları ile sağlanmalıdır anlamına gelir.

Yukarıda başvurulan sınıflandırma kullanılarak, API gibi görünüyor HTTP-based Type I (http://nordsc.com/ext/classification_of_http_based_apis.html#http-type-one) Eğer RPC URI-Tunneling ({kılacak, sizin URI'lerde eylemleri koymayın varsayarak [(3)]})

Ben genel amaç ile size yardımcı olur umarım.

Ocak

Bir kaç şey:

1) farklı yerlere yanıt başlıklarını koymak - HTTP başlık VE RESPONSE_CODE - kesinlikle karışıklığa neden olacaktır. Bazı geliştiriciler, tek bir yerde, diğer bazı kontrol edecektir. Eğer bu rota ile gitmek istiyorsanız, kesinlikle yanıt kodları HTTP başlıkları ve döndürülen XML arasında aynı olduğundan emin olun.

2) Sizin sunucu her tepki ile API sürümü dönmek zorunda DEĞIL. Sen tel üzerinde bit harcıyorsun. Istemci API belirli bir sürümünü istiyorsa, onlara istek o kadar göndermek var. Bunu onlara geri göndermek zorunda değilsiniz.

3) RESPONSE_CODE ve request_status birleştirin. HTTP bunu nasıl bak: 200-299 başarı anlamına gelir. 400-499 müşteri dilsiz demektir. 500-599 sunucu berbat demektir.

Eğer gerçekten REST hizmetleri inşa ediyorsanız, bu göz önünde bulundurun:

  • request_status, html yanıt kodu lehine damla olmalı (en az 200: OK, 400: Bad Request, 401: Yetkisiz, 403: Yasak ve 500: İç hata) response_code Lütfen belgelerin sorunun bir açıklama bulmak için gerekli olabilir.
  • Farklı formatı sağlamak istiyoruz, tepki biçimi url bağlı ama olmamalıdır Accept header arasında

Size bir örnek olarak kullanabileceğiniz iyi API kullanımınızı içeri aynı adlandırma kuralları ve muhafazayı kodlama API.

Ayrıca, API kullanarak örnek uygulamalar oluşturmak için deneyin ve hızlı bir şekilde eksiklikleri keşfedeceksiniz.

Eğer sürüm uç noktaları kullanarak düşündünüz mü? Onlar biraz daha planlama ve sizin açınızdan bakım gerektirebilir, ancak kullanıcılar kendi kodunu size parametreleri / dönüş değerlerini değiştirmeye karar her zaman yeniden yazmak zorunda değil seveceksiniz.

Eğer eski sürümleri deprecate ve daha sonra kaldırmak için bir plan ile gelip, bu çok acı kanıtlamak gerekir.

Eğer "tek bir URL / bitiş" fikri hakkında - Apache ile URL yeniden yazma kuralları yoluyla tek bir komut dosyası URL'lerin bir potansiyel olarak sınırsız sayıda hizmet olduğunu akılda tutmak. . Bu "son nokta" komut dizinde düzgün tanımlanmış bir htaccess dosyası ile otomatik olarak, örneğin, bu gibi gelen istekleri "harita" web sunucusu var anlamına gelir:

/foo/slice/1234 => /foo/?action=slice&oid=1234
/foo/dice/3456  => /foo/?action=dice&oid=3456
/foo/chop/4567  => /foo/?action=chop&oid=4567

Eğer tüm sonra "dinlendirici" URL'leri hizmet etmek istiyorum (ve HTTP isteği modları, DELETE, HEAD POST, PUT GET ile çalışmak için yapılabilir) karar verirseniz, bu çok yararlı olabilir.

etiketler