Endpointler
Swagger Docs sayfasında api üzerindeki tüm endpointler listelenmektedir. Bunların içinde önce çıkan ve sık kulanılan bazıları aşağıdaki gibidir:
/api/v1/core/sale/
: Siparişlerin bulunduğu endpointtir./api/v1/core/purchase/
: Alımların bulunduğu endpointtir. (sale ile tümüyle aynıdır, sadecebox
alanındaki bilgiler farklıdır)/api/v1/finance/saleinvoice/
: Faturaları bulundurur./api/v1/finance/purchaseinvoice/
: Alım faturalarını (gelen faturaları) bulundurur./api/v1/core/item/
: Ürünleri bulundurur./api/v1/core/category/
: Kategorileri bulundurur./api/v1/core/brand/
: Markaları bulundurur./api/v1/core/liquidstockunits/
: Birimleri bulundurur. Salt-okunur bir endpointtir./api/v1/core/currency/
: Dövizleri bulundurur. Salt-okunur bir endpointtir.
Metotlar
Propars API, REST standartlarında belirtildiği şekilde HTTP metotları üzerinde çalışmaktadır.
-
GET
: Bir ana endpointe (/api/v1/core/sale/
gibi) GET isteği gönderilirse o endpointin sunduğu objelerin bir listesi (sayfalama üstbilgisi ile) döner. Eğer id'si bilinen bir obje için oluşturulan bir resource'a (örnek/api/v1/core/sale/1/
) bu istek gönderilirse sadece o obje döner. -
POST
: Bir ana endpointe bu istek atıldığında o endpointin taşıdığı obje türünde yeni bir obje oluşur ve oluşan yeni obje cevap olarak dönülür. Bu isteğe dönülen cevapta (işlem başarılı oldu ise) HTTP kodunun "201 CREATED" olacağı göz önünde bulundurulmalıdır. -
PATCH
: Id'si bilinen bir objeye PATCH isteği gönderilirse objenin yalnızca gönderilen istekte bulunan alanları gönderilen şekilde güncellenir. -
PUT
: PATCH gibi çalışır. Farklılaştığı nokta şudur; bu istek gönderildinde sistemde bulunan objenin tüm alanları gönderilen istekteki veriye göre güncellenir. PUT isteği gönderilirken herhangi bir alanın istekte bulunmaması ya da boş bırakılmasının sistemdeki objeden de o alandaki veriyi sileceği unutulmamalıdır! Tüm alanlarındaki bilgileri bilinmeyen bir objeye kısmi güncelleme yapılmak isteniyorsaPATCH
tercih edilmelidir!Not: Bu kurallar api geneli için varsayılan kurallardır. Özel bir açıklama yapılmamış ise bu kurallar geçerlidir. Ancak bazı özel endpointler için özel kullanımlar olabileceği göz ardı edilmemelidir. Aşağıda bu özel kullanımlara örnekler listelenmiştir:
- PATCH isteği ile fatura iptali yapılmaktadır.
- POST isteği ile sipariş güncelleme yapılabilmektedir.
Sayfalama
Apide Limit-Offset Pagination kullanılmaktadır.
Herhangi bir endpointte bir listeleme yaparken kullanılacak olan sayfalama parametreleri limit
ve offset
şeklindedir. Kullanım örnekleri aşağıdadır:
-
İlk sayfayı varsayılan öge sayısıyla almak için(Varsayılanlar, limit=30, offset=0):
api/v1/core/sale/
-
Bir sayfada 25 öge olacak şekilde sayfalayıp 1. (ilk) sayfayı almak için:
api/v1/core/sale/?limit=25&offset=0
-
Bir sayfada 25 öge olacak şekilde sayfalayıp 2. sayfayı almak için:
api/v1/core/sale/?limit=25&offset=25
-
Bir sayfada 35 öge olacak şekilde sayfalayıp 3. sayfayı almak için:
api/v1/core/sale/?limit=25&offset=70
Filtreleme
Her endpointte o endpointteki objenin türüne ve alanlarına göre farklılaşan filtre parametreleri vardır. Bunlar da sayfalamadaki gibi url parametresi (query string) şeklinde kullanılmaktadır. Hangi endpointte hangi filtrelerin kullanılabilceğiyle ilgili detaylar Swagger sayfasında bulunmaktadır. (Örnek olarak sale endpointinin kabul ettiği filtreleme parametreleri bu sayfada 'Parameters' isimli tabloda bulunmaktadır) Ayrıca endpointlerle ilgili anlatımlarda da değinilecektir. Birkaç örnek aşağıdaki gibidir:
- Kaynağı website olan siparişler:
api/v1/core/sale/?source=website
- Durumu tamamlandı olan siparişlerde ikinci sayfa:
api/v1/core/sale/?offset=30&status=ST_DELIVERED
- Durumu tamamlandı ve kaynağı webiste olan siparişlerde ikinci sayfa:
api/v1/core/sale/?offset=30&status=ST_DELIVERED&source=website
Arama
Özel bir filteleme parametresi olan search
parametresi ile bazı endpointlerde objeler arasında arama yapılabilmektedir.
Aramanın objenin hangi alanlarında yapılıyor olduğu endpointe/obje tipine göre değişmektedir. Tüm endpointlerde arama özelliği bulunmamaktadır.
Örnek:
- Adında, kodunda veya barkodunda ABC123 geçen ürünler: api/v1/core/item/?search=ABC123