# General Information All endpoints follow the same conventions. An endpoint refers to a *resource.* {% hint style="warning" %} **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. {% endhint %} * **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

{% hint style="success" %} **Get** and **Find** refer to a single resource, while **Query** and **Fetch** ask for any number of resources (array). {% endhint %} ### 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 ```http GET {resourcePath}/find?fullName={fullName}&zipCode={zipCode} ``` or ```http 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. ```http GET {resourcePath}/query?fullName={fullName}&zipCode={zipCode} ``` ```http POST {resourcePath}/query { "fullName" : "{fullName}", "zipCode" : "{zipCode}" } ```