Genel Bakış
REST (Temsili Durum Aktarımı), World Wide Web (www) gibi dağıtımlı sistemler için geliştirilmiş bir yazılım mimari stilidir.
JSON kendini tanımlayan (self-describing) veri değişim formatıdır.
Logo RESTful API
- Veriyi, JSON dosyaları olarak saklar.
- Böylece ürün içerisinde gerçekleştirilen her işleme "JSON formatında bir URL yoluyla" erişimi mümkün kılar.
Bu da, web ve mobil uygulamalar için RESTful API'ı bu denli güçlü yapan özelliklerden sadece biridir.
REST'in avantajlarından bazıları;
- bileşen etkileşimlerinin ölçeklenebilirliği
- arayüzlerin genelliği
- bileşenlerin bağımsız dağıtımıdır.
REST aynı zamanda gecikme süresini indirgeyen, güvenliği güçlendiren ve yasal sistemleri içeren uygulama bileşenleri arasında bir aracı görevi görür.
REST API, HTTP çağrılarını yapabilen her dilde kullanılabilir.
Tasarım Prensipleri
URL'ler:
Pragmatik RESTful tasarımında bir numaralı prensip, her şeyi yalın tutmaktır. Taban URL'niz basit ve sezgisel olmalıdır.
Taban URL, API'ın tasarım sağlarlığı (affordance) için en önemli etkendir. Basit ve sezgisel bir taban URL tasarımı, API kullanımını da kolaylaştırır.
Sağlarlık, dokümana ihtiyaç duymadan herhangi bir şeyin nasıl kullanıldığının ifade edilebilen bir tasarım özelliğidir.
j-Platform WADL(Web Application Description Language)
http://host:port/logo/rest/?_wadl
http://host:port/logo/restservices/rest/?_wadl
İsimler
/getAllOrders yerine GET /orders
Çoğul
İki farklı türden kaynağı yönetmek için tekil isimler yerine çoğul isimler kullanmalısınız:
- Collection resource:
/users
2. Instance resource:
/users/007
Sürüm
URL'de sürümlemeyi (büyük, yani majör versiyonlar için) en yüksek kapsamında zorunlu hale getirmelisiniz.
Taban URL: https://<application uri>/rest/v{versiyon numarası}
Örnek URL: https://host:port/logo/rest/v1.0/orders
Hiyerarşik Yapı
Yapısını vurgulamak için URL'nin hiyerarşik doğasını (aggregation veya composition) güçlendirmelisiniz.
Örnek: Bir siparişin içerisindeki satırlar isteniyor.
GET /orders/1234/transactions/1
Kendini Tanımlayan (Self-descriptive):
Her bir kaynak, REST servisini açıklamak üzere servisler ve tanımlar yöntemlerini uygulamalıdır.
a. Swagger UI desteği bulunmaktadır.
b. Servisler yöntemlerinin amacı, yalnızca tasarıyı değil, aynı zamanda REST nesneleri üzerine yapabileceğiniz işlemleri de açıklamaktır.
GET /services çağrısı, tüm REST yöntemlerini ve REST içerisindeki tüm nesnelere ait tanımları döndürecektir.
http://host:port/logo/rest/?_wadl
c. Tanımlar yöntemlerinin amacı, REST nesnelerinin tasarısını açıklamaktır.
GET /orders/describe çağrısı, siparişler nesnesinin tasarısını döndürecektir.
Örnek URL:http://host:port/logo/rest/v1.0/orders/describe
Daha fazla bilgi için http://json-schema.org/
Güvenlik: OAuth2 & HTTPS
- Yetkilendirme'yi yönetmek için OAuth2 kullanabilirsiniz.
- OAuth2, gereksinimlerin ve istemci tiplendirmelerinin %99'una uyum sağlar.
- Her API/OAuth2 isteği için HTTPS kullanılabilir.
- Mümkün olduğu takdirde, oturum açmaktan kaçının
- Eğer gerekiyorsa her istek için kimlik doğrulaması yapın.
- (Stateless)
- Kaynak içeriğine göre yetkilendirme yapın. URL'ye göre değil.
- Kullanıcı Adı / Şifre yerine API anahtarlarını kullanın.
401 “Unauthorized” doğruluğu / kimliği teyit edilmemiş anlamına gelir.
“Bu isteğe yanıt verebilmem için geçerli kimlik bilgilerine ihtiyacın var."
403 “Forbidden” yetkiniz olmadığı anlamına gelir.
“Kimlik bilgilerini aldım, ancak üzgünüm, sana izin yok!"
599 “Logo Exchange Error” j-Platform' da yapılmak istenen işlem sırasında alınan hataya karşılık gelir.
"Fiş tarihi mali dönem içinde olmalıdır."
Kaynak Erişimi: (Liste + CRUD )
Ortak Sorgu Seçenekleri
Ad | Zorunlu | Varsayılan Değer | Değer Tipi | Anlamı |
Firm | Hayır | Kullanıcının varsayılan şirketi | İnteger | Kayıtların firma no'su |
Language | Hayır | Kullanıcının varsayılan dili | String | Dil adı |
Set | Hayır | “” | String | Uygulama değişkeni "set" değeri |
Örnek url: https://host:port/logo/rest/v1.0/orders?firm=1&language=TRTR&set=DRF