General Information

All endpoints follow the same conventions.

An endpoint refers to a resource.

Important

The http-method GET, POST, PATCH etc, is completely irrelevant! http-methods have no specific meaning, they are only used to provide a useful interface for the API clients.

I found it very confusing and limiting trying to give http methods a certain meaning. Like POST is create resource, PATCH is update resource or GET is getting a resource. Such patterns were created when REST was invented (many years ago) , when REST was used to "CRUD objects" (Create Read Update Delete objects).

Modern web-services are built with the REST technology but they are much more than simple CRUD services. REST APIs serve clients needs and provide functionality which is not only CRUD (see difference between REST and SOAP). In fact, modern web-services use REST more as a protocol to provide functionality resources.

The same is true for http-status codes. They are technical state representations that should not be misused to attribute business significance to them.

• Modern APIs serve business needs.

• Endpoint functionality derives from the clients needs.

• Endpoint functionality uses verbs from the business domain (which is not: create, read, update, delete)!

Endpoint functions for read access

An endpoint function provides functionality on a resource. There are four different basic (business) types of use:

• Get an existing resource or an error - single record or exception

• Find an existing resource or null - single record or null

• Query returns an array [0..n] of resource descriptors (metadata only).

• Fetch returns an array [0..n] of resources incl. data.

If and how these functions are implemented depends on the endpoint.

/Docs Endpoint

Get and Find refer to a single resource, while

Query and Fetch ask for any number of resources (array).

Using a resource path

Get, for example, should be available a http GET {resourcePath}/{resourceId}. If the client asks for a resourceId that does not exist, the endpoint returns http-404 (NotFound), which is in-line with best practices and http-specification, which means: "Resource path does not exists". The Find a specific resource is the same endpoint but the interpretation of the results would be different: 404 means "resource not found" while 404 with Get means "something went wrong because an expected resource does not exist"

Using Query parameters

Both functions, Get and Find can be implemented using query parameters. For example:

• GET {resourcePath}?fullName={fullName}&zipCode={zipCode}

This function will never return http-404 (NotFound) because the resource path always exists! Instead, this function will return, in case the expectation is not met a http-400 (BadRequest) with a well-defined response message. The meaning of BadRequest is that the client send something to the service which did not lead to the expected result.

The difference between Find an Get in this case is:

• Get returns http-400 (BadRequest) if there is zero or more than one resource that matches the provided query parameters. Expectation is: exactly one!

• Find returns a http-204 (NoContent) if there is no match (expectation met: success response). It responds with http-400 (BadRequest) if there is more than one resource that match the provided query parameters (error-case).

Endpoint function and their representation

It is important to understand that the endpoint function (which is the business perspective on what the client is asking for) is completely independent from their (technical) implementation. For example: Get with query parameters might not be implemented and a Find might be represented like this

GET {resourcePath}/find?fullName={fullName}&zipCode={zipCode}

or

POST {resourcePath}/find

{ 
    "fullName" : "{fullName}", 
    "zipCode" : "{zipCode}" 
}

However, all endpoints should follow the same pattern, as mentioned above.

Query and Fetch

Query and Fetch are use the "receive" zero or more resources. Basically, both functions server the same need, with the difference, that Query might omit data (payload) and return descriptive information only. For example, a Query fullName={fullName}&zipCode={zipCode} might respond only the resource Ids, probably followed by a Get (by Id) to read the resource data. Find, on the other hand, should respond all matching resources incl. their data.

Again, if and how the functionality Query / Find is implemented depends on the endpoint.

GET {resourcePath}/query?fullName={fullName}&zipCode={zipCode}

POST {resourcePath}/query

{ 
    "fullName" : "{fullName}", 
    "zipCode" : "{zipCode}" 
}