Difference between revisions of "Coding standards"
(→RESTful URL endpoints) |
(→RESTlike versus RESTful) |
||
| Line 15: | Line 15: | ||
===RESTlike versus RESTful=== | ===RESTlike versus RESTful=== | ||
| − | Pure | + | Pure REST''ful'' is something of a heavyweight abstraction (and enthused by the puritanical bore), and places demands on clients that they often simply cannot accommodate efficiently. Therefore, a REST''like'' approach is the happy medium, where we adhere use the traditional contract approach (a specified set of URLs and payload definitions). This simple approach is understood by all and can be achieved in the smallest or oldest of architectures. |
===URL structure=== | ===URL structure=== | ||
Revision as of 08:24, 27 June 2019
Contents
Object properties
Getters
Avoid throwing exceptions. A getter should provide access to the field, and should not result in an exception. There are occasions when this rule can be relaxed (such as indeterminable exceptions like OutOfMemoryException, or deliberate exceptions such as IllegalStateException), but things like NullPointerExceptions should not occur.
Must be repeatable. Each call to a getter should result in the exact same response. As a general rule, you should not create new objects. If you do, you should make sure they are always guaranteed to be equal (this may be hard if you are not responsible for the other code). The desired behaviour is that of a const method in C++, so that calling the method on an object does not change the state of the object.
Setters
Order cannot matter. The order in which setters are called should have no effect on the end result. Calling setA() then setB() should end with the same result as setB() followed by setA().
RESTful URL endpoints
RESTlike versus RESTful
Pure RESTful is something of a heavyweight abstraction (and enthused by the puritanical bore), and places demands on clients that they often simply cannot accommodate efficiently. Therefore, a RESTlike approach is the happy medium, where we adhere use the traditional contract approach (a specified set of URLs and payload definitions). This simple approach is understood by all and can be achieved in the smallest or oldest of architectures.
URL structure
The API endpoints should incorporate the plural of the entity (i.e. "users" rather than "user").
/<category>/<entities>/<entityId> /<category>/<entitiesA>/<entityIdA>/<entitiesB>/<entityIdB>/<entitiesC>/<entityIdC>
When the identifier is something other than an identifier, we alter the path variable accordingly:
/<entitiesByName>/<name> /<entitiesBySize>/<size> /<entitiesById>/<entityId>
As the "ById" pattern is so common, we choose to shorten it by removing the 'ById', so that it becomes:
/<entities>/<entityId>
Optional parameters (such as those used for ordering results, for example) should not appear in the URL path, but in the query parameters.
Examples
Here are some examples:
/user-management/users/76516745
/user-management/usersById/76516745
/user-management/usersByName/fbloggs
/user-management/users/76516745/features
/user-management/users/76516745/features/{featureId}
/user-management/groups/1872/users?sort=name
Verbs
| Method | Purpose | Example | Notes |
|---|---|---|---|
| POST | Create | /users |
If the entity in the body contains a userId, it should try to use that identifier. This behaviour is useful for import/export between systems. |
| GET | Read | /users/<userId> |
|
| PUT | Update | /users/<userId> |
If the entity in the body contains a different userId, it might try to effectively rename/move the entity. |
| DELETE | Delete | /users/<userId> |
Other actions should be implemented so that the "verb" appears at the end of the URL. For example, if there is a situation where you want to play (verb) a set of songs, the URL would look something like:
/song-book/songs/197263541675243/play
