# First class rest APIs with symfony

## Who
- @michaelcullumuk
- Michael Cullum
- Works for bud. (2 weeks ago)
- core team at syfony
- fig working group
- fig security

## WTF IS REST?

- Paper by roy fielding
- dry and boring
- Representational State Transfer (REST)
- Communicating state

### How to comply to REST

- Uniform interface
    - Each api works the same at a ui level
    - Gives all data to client that client can then use to give back and modify
    - use mime types
    - Hyperdata. Link to other data.

- Stateless
    - No session
    - Self contained in one request
    - Auth in the request

- Cacheable
    - If not cacheable, you need to tell clients this

- Client-Server need to be distinguishable
    - Independently build client and server

- Layered system
    - May not be talking to an end user
    - May be other applications or proxies or API in between
    - (like micro services talk adding auth or similar at certain APIs)

- Code on demand
    - Be able to run code on the server
    - Legacy.
    - bit weird
    - considered optional

- USE HTTP WELL
    - HTTP is your friend
    - RESTful does not discuss http
    - HTTP VERBS
    - USE THEM ALL
    - (Google crawling with GET, where they hit a GET verm delete end point)
    - USE RESPONSE CODES
    - Rate Limiting + use codes (429)
    - 503 for when there's issues

- In symfony
    - Use the constants

## Errors
Exception controller
Does logging
Return our json response
getErrors() handles error once in one function, included for all controllers

## DTO ALL THE THINGS
- in PHP we tend to use arrays lots
- Decode some JSON and might put it into array
- bad as we have no typing
- We can use typing to move complication and validation of data to PHP level
- Reduces typos etc
- In symfony we can auto-hydrate stuff
    - mapAndPersist
    - A dataTransferObjectConvertor

## Validation
- Exceptions
    - Exceptional case
    - Should expect edge cases and failings
    - Remove control from controllers
        - isValid in the controller forces us to have logic in the controller
        - instead try and persist an object, throw new exception

## Output
    - Symfony serialiser component
    - Choose output types easily
    - Transformers to migrate the data from an entity and map to response data
    - Allows us to focus on API respires not database layer entities
    - PHPLeaue FRACTAL (for transformers)
    - Transformers allow us to be explicit!
    - Using fractal can build our json but bhandke collections, pagination etc

## Nobody likes pagination
    - Pain in the arse
    - Clients need to work out logic for reading
    - Server side we have extra logic, limits etc

    How to do it then?
    - Do it
    - Link to next and previous (hyper media)
    - Detail current page
    - Detail total number of pages
        - Assuming you know
        - Disabling totals speeds things up
        - Perhaps client option
    - Use paginator tools
    - Really simple controllers

## Sorts and filters
- query string
    - pagiantion
    - sorting
    - includes
    - filters

## Tools
- Api platform
    - EZ PZ
- FOS REST
    - automatic routing
    - slugs etc

# RECAP
PRINCIPLES OF REST
USE HTTP WELL - verbs and codes
ERROR handling, abstracting validation. Handle expectations for response codes
DTOs and param convertor
Validation bubbles, catch and re-throw
Formatting output with transforms
Pagination - annoying but easy, if we p[ass via repos.
Sorts and filters similar to Pagination
Tools!!! Use em.]



# Useful Link
https://github.com/FriendsOfSymfony/FOSRestBundle
https://github.com/whiteoctober/Pagerfanta
https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
https://en.wikipedia.org/wiki/Data_transfer_object
https://fractal.thephpleague.com/
https://api-platform.com/