# API Geliştirme Modeli

###### tags: `completed`

## Amaç
Bu belgenin amacı kurum içerisinde API geliştirmelerine model ve referans bilgilerini geliştiricilere sağlamaktadır.

## Prensipler

### RESTFul Tasarım
API operasyonları ve veri desenleri tasarlanırken RestFul prensiplere uygun olarak tasarlanır.

Tasarım yapılırken, tüm Sistem Geliştirme, Kurumsal Mimari ve BT Güvenlik ekiplerinin görüşü alınarak ilerlenir.

Görüşler tüm ekiplerce değerlendirilir.

>**Referanslar**
https://restfulapi.net/rest-architectural-constraints/
https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design
https://hackernoon.com/restful-api-design-step-by-step-guide-2f2c9f9fcdbf
https://medium.com/@__cure/rest-anti-patterns-b128597f5430

### Platform

Geliştirmeler için **.Net Core Web Api** platofrmu kullanılır. Dökümantasyon desteği için **Swashbucle** ile sağlanır.

Geliştirilecek operasyonlar ve veri modelleri için kod içerisinde anlaşılır ve tam dökümantasyon yapılır.

Tüm birimlerlerin görüşünün tamamlama aşaması tüm operasyon ve modellerle ilgili tanımların netleştiği ve belgelendirildiği zamandır.

>**Referanslar**
https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-3.1&tabs=visual-
https://docs.microsoft.com/en-us/aspnet/core/tutorials/first-web-api?view=aspnetcore-3.1&tabs=visual-studio
https://github.com/domaindrivendev/Swashbuckle.AspNetCore

### Yaşayan Belgelendirme
Operasyonlar ve modeller üzerinde her türlü geliştirme yine proje içerisinde belgelendirlecektir.

Belgelendirme kuralları;
-Belgelendirme dili İngilizcedir.
-Her operasyonun ne iş yaptığı tereddüt yaratmayacak şekilde tanımlanacaktır.
-Tüm parametrelerin ne işe yaradığı ve hangi verileri alacağı tanımlanacaktır.
-Kullanım senaryoları ile ilgili örnek veriler sağlanacaktır.
-Okunabilirliği arttırmak adına gerektiği yerde belgelendirme için *markdown* formatı kullanılacaktır.

>**Referanslar**
https://commonmark.org/help/
https://stackoverflow.com/questions/39924144/how-to-format-swagger-2-0-text-descriptions
https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-3.1

### Hata Kodları
Hata kodları için HTTP dönüş kodlarının kullanılmayan http kodları kullanılır.

Operasyon bazında her bir hata farklı kod ile döner. Hata ile ilintili farklı bir model sağlanıyorsa bu tanımlama da belgelendirilir.

:::danger
**500** Hata kodu ile yanıt dönen operasyonlar hatalı olarak değerlendirilecektir.
:::

>**Referanslar**
https://www.restapitutorial.com/httpstatuscodes.html
https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
https://developer.mozilla.org/en-US/docs/Web/HTTP/Status