Difference between revisions of "Coding standards"
(→RESTlike versus RESTful) |
(→URL structure) |
||
| Line 46: | Line 46: | ||
===URL structure=== | ===URL structure=== | ||
| − | The API endpoints should incorporate the plural of the entity (i.e. "users" rather than "user"). | + | The API endpoints should incorporate the plural of the entity (i.e. "users" rather than "user"). An entity is always a '''noun'''. |
/<category>/<entities>/<entityId> | /<category>/<entities>/<entityId> | ||
Revision as of 06:58, 2 September 2019
Contents
Object properties
Getters ("Accessors")
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 ("Mutators")
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().
Naming convention
| Pattern | Notes |
|---|---|
| get<field>() | Get the value of 'field'. It does not modify anything. |
| is<field>() | Get the value of a boolean named 'field'. It does not modify anything. |
| has<field>() | Get the value of a boolean named 'field'. It does not modify anything. |
| find<criteria>() | Find a set of objects. It will always return a collection (typically a list), which might be empty. It does not return null. |
| create<criteria>() | Create a single object based on a set of parameters. This is a factory method. |
RESTful URL endpoints
RESTlike versus RESTful
Pure RESTful (i.e. HATEOAS) is a heavyweight abstraction (and enthused by the puritanical bore) that places demands on clients that they often simply cannot accommodate efficiently. Therefore, a RESTlike approach is the happy medium, where we 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, but is at the expense of automation of certain developer tooling.
When developing an endpoint, focus on the client as that is your customer; the easier it is to consume, the better your reputation.
Assuming that the length of time to develop client-side code is less than the time for which it is expected to be used, efficiency is the most important part of an API. Understanding is secondary. The second is a matter of the client-side developer learning once. Once done and let loose in the live environment, efficient operation is by far the most important consideration. Reducing the number of calls to achieve something is important. Savings of 10ms are important. Consider the object graph when designing your API, but it is only one aspect you need to consider; focus on ensuring there is no recursion, circular dependencies, etc. For example, provide a mechanism to get users, to get groups, and to get membership.
/user-management/users/111 /user-management/users/111/groups /user-management/groups/999 /user-management/groups/999/members
Lastly, in anything other than trivial situations, it is rare that any or all parts of the object graph can be updated by clients. In most cases, you'll find clients need to update only a tiny portion of the graph. You should only provide interfaces for those that are needed.
URL structure
The API endpoints should incorporate the plural of the entity (i.e. "users" rather than "user"). An entity is always a noun.
/<category>/<entities>/<entityId> /<category>/<entitiesA>/<entityIdA>/<entitiesB>/<entityIdB>/<entitiesC>/<entityIdC>
When the entity id 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 certain song, the URL would look something like:
/song-book/songs/197263541675243/play
