URL

 

URL

* Protokol  HTTPS olmalıdır.

* Eğerki domain name içerisinde api keywordu geçmiyorsa domainden sonra eklenmelidir.

    - https://www.myapp.com/api

* Eğerki domain name içerisinde api keywordu geçiyorsa aşağıdaki gibi olmalıdır.

    - https:/www.googleapis.com/v1/documents

Version

* Sadece pozitif doğal sayılardan oluşmalıdır. Decimal olmamalıdır.

* Version bilgisi 3 farklı şekilde tanımlanabilir. Best practise olarak Query String ile asla version bilgisi göndermemeliyiz. 

* Url, Header veya Query String.

* Url içerisinde ifade etmek için v prefixi kullanılır.

    - https://www.myapp.com/api/v1

Entity

 

* Sadece tek bir kelimelik noun olmalıdır. Verb kullanılmaz.

   - /api/v1/orders

   - /api/v2/employees

   - / api/v2/travels

ID parameters

* Url içerisindeki ilk opsiyonel alandır. Specifik bir entity ile çalışma yapacaksak Id paremetresiyle o entitye ulaşırız.

* ID parametresi GET, PUT, DELETE http verbleriyle ilgilidir. POST için Id kulanılmaz.

    - /api/v1/order/17

Query Parameter

Query ve Id parametrelerini  genellikle Get ve Delete requestlerinde kullanırız. Aşağıda 17 Id parameter iken fromDate ve toDate query parameterdır. Genellikle required parametreler route ile optional parametreler query ile gönderilir

- /api/v1/orders/17/items?fromDate = 12-12-2018&toDate=2-2-2019

Authentication Token, Content-Type ve Content-Encoding bilgileri URL'in bir parçası olarak değil Header parametreleriyle göndermeliyiz. Query ve Route parametreleri güvenli değildir çünkü buralara koyulmuş parametreler visibledır ve  herkes tarafından görüntülenebilir.

Id Parametresi spesifik primary bir resource yada resourcesları elde etmek için kullanılırken, Query Parameter bu resourceları sort/filter etmek için kullanılır. 

Sub Entity

* Optisiyonel bir alandır. 

* Bir entitye ait alt entityleri elde etmek istediğimizde kullanılır.

örn. Order Numberı 17 olan itemları listemek istediğimiz zaman order entity, item ise sub entity olmaktadır.

- /api/order/17/items

Singular Or Plural

ID parameterda geriye sadece tek bir result dönmeli. Bu yüzden entity ismi tekil yani  order olmalı. Query stringde ise geriye 0 ve n tane entity dönebilir. Bu yüzden orders yani çoğul olmalı 

* /api/v1/order/17    -> returns single order 

* /api/v1/orders?startsWith=a -> returns 0..N order.

Good RESTful URL examples

List of magazines:

GET /api/v1/magazines.json HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript

Filtering and sorting are server-side operations on resources:

GET /api/v1/magazines.json?year=2011&sort=desc HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript

A single magazine in JSON format:

GET /api/v1/magazines/1234.json HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript

All articles in (or belonging to) this magazine:

GET /api/v1/magazines/1234/articles.json HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript

Specify query parameters in a comma separated list:

GET /api/v1/magazines/1234.json?fields=title,subtitle,date HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript

Add a new article to a particular magazine:

POST /api/v1/magazines/1234/articles.json HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript

Bad RESTful URL examples

Non-plural noun:

GET /magazine HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript

GET /magazine/1234 HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript

Verb in URL:

GET /magazine/1234/create HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript

Link