# Automated Layouts Backend - API Research

# RMM - Richardson (REST) Maturity Model

---
# Level 0: The Swamp of POX

* Single endpoint
* No HTTP verbs
* No reponse statuses
* Just transferring documents (xml, json, whatever) with request details

###### POX - Plain Old XML
---
# Level 1: Resources

* Introducing resources
* Dedicated endpoints for specific resources

---
# Level 2: HTTP Verbs

* Resource-specific endpoints
* Using different HTTP request types
* Responses with proper statuses

---
# Level 3: Hypermedia Controls (HATEOAS)

* Api is hypermedia-controller - user might figure out what to do next just from first response
* additional `link` object provided along with every resource shows what's possible to do
* `rel` property shows relation to current resource
* `href` property shows what endpoind is responsible for resource

"links": [
    {
        "href": "https://api.foo.com/v1/customer/users/ALT-JFWXHGUV7VI",
        "rel": "self",
        
    },
    {
        "href": "https://api.foo.com/v1/customer/users/ALT-JFWXHGUV7VI",
        "rel": "delete",
        "method": "DELETE"
    },
    {
        "href": "https://api.foo.com/v1/customer/users/ALT-JFWXHGUV7VI",
        "rel": "replace",
        "method": "PUT"
    },
    {
        "href": "https://api.foo.com/v1/customer/users/ALT-JFWXHGUV7VI",
        "rel": "edit",
        "method": "PATCH"
    }
]

###### HATEOAS - Hypermedia As The Engine Of Application State
---

# Conclusion

### Level 2 is enough :)

### Worth discussing:
* Namespaces - per module (ex. `/namespace/users/:id`)
* Versioning - global/namespace/controller level
* One guidelines to rule them all - it's nice to have one source of truth in case if something become `kwestio sporno`
* No more responses with status `200` and `success: false`

---

docs:
[PayPal Api standard](https://github.com/paypal/api-standards/blob/master/api-style-guide.md)
[OpenAPI](https://github.com/nestjs/swagger)
[Haufe API Style Guide](http://work.haufegroup.io/api-style-guide/)
[HAL spec](http://stateless.co/hal_specification.html)
[jsonapi docs](https://jsonapi.org/)
[Microsoft API best practices](https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design)
[API Richardson Maturity Level](https://martinfowler.com/articles/richardsonMaturityModel.html)