Rest Servis Best Practises

By Alper Akalın Last updated Jul 28, 2018

Restful bir servisin tasarlanması geliştirilmesinden daha zordur. Java Restful Servisin geliştirilmesi bazı kod parçalarının bir kaç anotasyon ile işaretlenmesinden ibarettir denilebilir. Resource tanımlamalarında uygulanan tasarıma azami dikkat edilmelidir.

1- Resource-Kaynak tanımları serviste kullanılacak verilerin konumunu belirleyen adreslerdir. Bu adresler unique-eşşiz özellikte olmalıdırlar. Yani URI özelliğe sahip olmalıdırlar.

2- Resource Tanımlarında isimlendirme fiiller üzerinden değil isimler üzerinden yapılmalıdır. Yapılacak işlemlere yani fiile rest api karar verecektir.

3- Resource isimlendirmelerde çoğul ifadeler tercih edilmeli ve karışık kullanımdan kaçınılmalıdır.

4- Resource’lar arasında veri tabanı tabloları arasındakine benzer bir ilişki var ise subResoruce tanımları kullanılmalıdır. Örneğin herhangi bir facebook durum mesajının bir yorumu olabilir. Bu durumda yorum alt kaynak – subResource olarak tanımlanmalıdır.

5- HTTP metodlar spesifikasyon tanımları doğrultusunda kullanılmalıdır. Örneğin put/post metodlar birbirlerinin yerine kullanılmamalıdır. Yerinde kullanım için Idempotent özelliğinden yararlanılabilir.

6- Resourcelar filtreleme ve sayfalama yapılabilecek şekilde geliştirilmelidir. Yani belirli aralıklardaki veriler sayfa sayfa gösterilebilir olmalıdır. Böylece performans ve kullanıcı memnuniyeti artırılabilir.

7- Request ve response’ta kullanılacak doküman tipi header’da kesin olarak belirlenmelidir. Böylece server side uygulama ile client side uygulama arasındaki iletişim kalitesi artırılacaktır.

8- HATEOAS, Hypermedia as the Engine of Application State presibi ile yaratılan resource’lar için yönlendirme-navigasyon linkleri oluşturularak client side uygulama ya da kullanıcıya yol gösterilmelidir.

9- Hata yönetimi en iyi şekilde tasarlanarak client side uygulama veya kullanıcının oluşan hatalarda maximum düzeyde bilgi sahibi olması sağlanmalıdır

10- Hata yönetiminde standart statü kodları kesinlikle kullanılmalıdır. Böylece bir standardizasyon sağlanmış olacaktır. Burada 2XX ile 5XX arasındaki kodlar kullanılarak standart bir yapı oluşturulabilir.



<pre class="theme:eclipse lang:java decode:true " > 
javax.ws.rs.core.Response.Status
 
public enum Status {
 
	OK(200, "OK"),
        CREATED(201, "Created"),
	ACCEPTED(202, "Accepted"),
	NO_CONTENT(204, "No Content"),
	MOVED_PERMANENTLY(301, "Moved Permanently"),
	SEE_OTHER(303, "See Other"),
	NOT_MODIFIED(304, "Not Modified"),
	TEMPORARY_REDIRECT(307, "Temporary Redirect"),
	BAD_REQUEST(400, "Bad Request"),
	UNAUTHORIZED(401, "Unauthorized"),
	FORBIDDEN(403, "Forbidden"),
	NOT_FOUND(404, "Not Found"),
	NOT_ACCEPTABLE(406, "Not Acceptable"),
	CONFLICT(409, "Conflict"),
	GONE(410, "Gone"),
	PRECONDITION_FAILED(412, "Precondition Failed"),
	UNSUPPORTED_MEDIA_TYPE(415, "Unsupported Media Type"),
	INTERNAL_SERVER_ERROR(500, "Internal Server Error"),
	SERVICE_UNAVAILABLE(503, "Service Unavailable");
 
</pre>

javax.ws.rs.core.Response.Status

public enum Status {

OK(200, "OK"),

CREATED(201, "Created"),

ACCEPTED(202, "Accepted"),

NO_CONTENT(204, "No Content"),

MOVED_PERMANENTLY(301, "Moved Permanently"),

SEE_OTHER(303, "See Other"),

NOT_MODIFIED(304, "Not Modified"),

TEMPORARY_REDIRECT(307, "Temporary Redirect"),

BAD_REQUEST(400, "Bad Request"),

UNAUTHORIZED(401, "Unauthorized"),

FORBIDDEN(403, "Forbidden"),

NOT_FOUND(404, "Not Found"),

NOT_ACCEPTABLE(406, "Not Acceptable"),

CONFLICT(409, "Conflict"),

GONE(410, "Gone"),

PRECONDITION_FAILED(412, "Precondition Failed"),

UNSUPPORTED_MEDIA_TYPE(415, "Unsupported Media Type"),

INTERNAL_SERVER_ERROR(500, "Internal Server Error"),

SERVICE_UNAVAILABLE(503, "Service Unavailable");

</pre>

11. Servis geliştirmelerinde zaman zaman servisin Richardson Maturity Model uyumluluğu denetlenerek servisin kalitesi ölçülmelidir.

Richardson Maturity Model

Kaynak : Enterprise Java

rest service restful