Summary of discussion about contents this repo should have

[siemensikkema]

How to write APIs
    Documents
        how-to-write-apis.md

        solution architecture
    API Design styles
        REST(ish)
        gRPC
            advantages
            disadvantages
        hypermedia
            JSON linked list
            index/root for starting point
            metadata what I'm allowed to do
            advantages
            disadvantages
        GraphQL
            advantages
            disadvantages
    Manifesto
        Overview
        Ideal Goal
    Contents
        Errors
            Elaborate on Peter's work
            remove vapor specifics (old versions)
        Endpoints
            anatomy
                method
                path
                resources
                version
                query params
        Timeouts
            missing
            incoming
            outgoing timeouts
        Headers
            don't require accept header
            mention accept-language
            N-Meta
                include or stay Nodes agnostic
                traceability/debugging section
                    good practice to have identifying info per request
            consider removing
                facebook/insta/twitter/linkedin/lat/lon
        Image manipulations
            S3 specific?
            should we keep it?
            explain different available approaches
                one example what we use: S3
        Pagination
            explain different paginators
                offset
                cursor
            why it's needed
            recommended structure
        Localization
        Status codes
        Response body
            keep in data wrapper
            remove the no-response example
            remove the error example
        Auth
            OAuth
            Basic
            Hawk
            Authentication vs. Authorization
            JWT
            Anonymous users
            blacklisting/whitesting
            ip black/white listing
            rate limiting, exp. backoff
        BFF / Thin Clients
            don't require the client to execute series of steps if the backend can do it instead in 1 call
            make the client as dumb as possible
            specialized
            careful to not make the backend to brittle, unflexible
        Caching
            etags
        Things to avoid
            inconsistencies in eg. naming, structure
            state
            wrapping xml in json

        Documentation
            Changelogs to updates
        Testing
        Mocking
        OWASP
        Files
            Streaming
        Health endpoint
    General
        Tone
            professional, authoritative
        General, Nodes agnostic document
        be relatively complete but have recommended approaches
        Create new repo

[siemensikkema]

This is just a one to one copy of my mind map. Let's flesh it out a bit and then involve Casper.

[steffendsommer]

@siemensikkema awesome. Maybe we should move ownership to nodesagency org instead as it's (fairly) platform agnostic?

[siemensikkema]

Include discussion about url formats. eg. /posts/:id/comments/:id vs /comments/:id