[jira] [Created] (FC-77) rest api not restful

["Shawn McKinney (JIRA)" <ji...@apache.org>]

Shawn McKinney created FC-77:
--------------------------------

             Summary: rest api not restful
                 Key: FC-77
                 URL: https://issues.apache.org/jira/browse/FC-77
             Project: FORTRESS
          Issue Type: Improvement
    Affects Versions: 1.0.0-RC39
            Reporter: Shawn McKinney
             Fix For: 2.0.0-M1


The fortress rest component does not adhere to the principles laid out in R.T. Fielding's "Principled design of the modern Web architecture".

The fortress rest services simply wrap the apis.  All use put which is convenient for internal usage but creates problems for external clients due to a complicated and non-standard interface.

The fortress rest apis should follow established best practices, e.g.:

1. Use nouns but no verbs
currently the service names are same as api names, e.g. 
addUser, updateUser, readUser, findUsers, etc

instead should be

/user 

2. GET method and query parameters should not alter the state

fortress rest services are all 'puts' currently

3. Use plural nouns

i.e. /users to return collections and /user to return single

self explanatory

4. Use sub-resources for relations

5. Use HTTP headers for serialization formats

6. Use HATEOAS

Hypermedia as the Engine of Application State is a principle that hypertext links should be used to create a better navigation through the API.

7. Provide filtering, sorting, field selection and paging for collections

8. Version your API

9. Handle Errors with HTTP status codes

10. Allow overriding HTTP method

items in this list copied from here:

"10 Best Practices for Better RESTful API"
http://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-restful-api/

this list is not complete.  This work will have to be done in parts.  The old services (i.e. core api wrappers) can remain in place.  Over time, new services will be added that closely follow the principles of rest.  The same fortress core apis can be used for the new services, but will be published to the client in a traditional rest format.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)