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, sadece box 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 isteniyorsa PATCH 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:





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