REST API Tasarımı - Naming Conventions

Giriş
Bu yazıdaki başlıkları buradan aldım.

Kısaca

1. REST isimlerinde noun kullanmak gerekir. İsimlerin çoğul olması iyidir.  Şöyle yaparız

# Kötü
http://api.example.com/v1/store/CreateItems/{item-id} 
#İyi
http://api.example.com/v1/store/items/{item-id}

Eğer isimler çok uzunda çizgi karakteri ile ayrılabilir. Şöyle yaparız

http://api.example.com/v1/store/vendor-management/{vendor-id}
http://api.example.com/v1/store/item-management/{item-id}/product-type
http://api.example.com/v1/store/inventory-management

HTT Verb'leri REST isminde kullanılmaz.   Şöyle yaparız

# Get Read employee with employee id 8345
example.com/employees/8345

#POST— Create an employee
example.com/employees

# PUT— Update employee with employee id 8345
example.com/employees/8345

#DELETE — Delete employee with employee id 8345
example.com/employees/8345

2. REST isimlerinde versiyon vermek gerekir. Yukarıdaki örnekte var

3. Filtreleme vs gibi şeyler için parametre kullanmak gerekir.  Şöyle yaparız

http://api.example.com/v1/store/items?group=124

http://api.example.com/v1/store/employees?department=IT&region=USA

HTTP Verb'leri Ne İşe Yarar
Rest tasarımında HTTP verb'lerini kullanmak gerekir.

GET     /items      # Read all items
GET     /items/:id  # Read one item
POST    /items      # Create a new item
PUT     /items/:id  # Update one item
DELETE  /items/:id  # Delete one item

Post ve Put
Post ve Put benzer şeyler çağrıştırdıkları için kafa karıştırıyorlar. Post create,insert Put ise update için kullanılır diye anladım. Post için primary key kullanmaya gerek yok

POST   /items        #=> create

Put için primary key kullanmaya gerek var.

PUT    /items/1      #=> update

1. Accept and respond with JSON

Örnek
Şöyle yaparız

GET /api/something?param1=value1
Accept:  application/xml (or application/json)

2. Use nouns instead of verbs in endpoint paths
Açıklaması şöyle

We shouldn’t use verbs in our endpoint paths. Instead, we should use the nouns which represent the entity that the endpoint that we’re retrieving or manipulating as the pathname.

This is because our HTTP request method already has the verb.

Örnek
Şöyle yaparız. Burada endpoint'te customer kelimesi kullanılıyor. Her Http verb ise kodda Createcustomer(), UpdateCustomer() gibi anlamlı kodlara gönderiliyor.

• For creating new customer:
  URI = /customer/, type = POST, Methodname = CreateCustomer()
• For updating:
  URI: /customer/{id}, type = PUT, method = UpdateCstomer()
• For Delete customer:
  URI = /customer/{id}, type = DELETE, Methodname = DeleteCustomer()
• For View:
  URI: /customer/{id}, type = GET, method = GetCustomer()

Örnek
Hatta şöyle sınıflar tanımlanabilir.

class Category {
    public static Category[] getList();
    public static Category getById($id);
    public static Subcategory[] getSubcategories($id);
    public void fetchDetails();
}

class Subcategory{
    public static Subcategory getById($id);
    public static Product[] getProducts($id);
    public void fetchDetails();
}

3. Name collections with plural nouns
Eğer endpoint bir collection ile temsil ediliyorsa çoğul isim kullanmak daha iyi olabilir.


4. Nesting resources for hierarchical objects
Örnek
Şöyle yaparız

'/articles/:articleId/comments'

5. Handle errors gracefully and return standard error codes

6. Allow filtering, sorting, and pagination

Örnek - pagination
Rest sorguları aslında biraz SQL cümlelerine benziyor. Bazen tek bir nesne, bazen liste bazen de sayfalama yapmak gerekiyor.

Şöyle yaparız
Tek bir nesneyi çekmek için

GET /authors/{id}

Liste şeklinde çekmek için

GET /authors/

Sayfalar şeklinde çekmek için

GET /authors?page={page}

Eğer ağaç şeklinde nesnelerimiz varsa önce ana nesneyi, daha sonra ağacın altındaki alt nesneleri bulmak gerekir.


7. Maintain Good Security Practices
Rest Authentication
Authentication için 3 yöntem var.

1.basic http authentication
2.Oauth 1.0
3. Oauth 2.0

1. Basic Authentication yönteminde HTTP Authorization header alanı kullanılıyor. Bu yöntemin eksisi, her istekte credentials'ın tekrar gönderilmesi, tekrar authenticate edilmesi. Bu işlemin CPU maliyeti var. Daha detay için HTTP Basic Authentication Nedir? yazısına bakabilirsiniz.

2. OAuth1 yönteminde access key URL ile gönderiliyor.

8. Cache data to improve performance

9. Versioning our APIs
Açıklaması şöyle

There are various strategies that one can employ to version the APIs. The following are a few commonly used ones:

1. Using URI versioning. In this approach, we use a version number identifier in the REST API URI to indicate the different version of the API

2. Using request parameter based versioning. In this approach, we use a HTTP request parameter to identify the API version

3. Custom HTTP header based versioning. This approach uses an HTTP request header to identify the API version

4. Media Type based versioning. In this approach, we use HTTP “Accept” header to identify the version

All these approaches are commonly used and have their own merits and drawbacks. You can refer to this GitHub URL to find detailed example on each of these techniques.

URI versioning

Açıklaması şöyle

Versioning is usually done with /v1/, /v2/, etc. added at the start of the API path.

10. API Gateway
API Gateway yazısına  taşıdım