Chapter 4: Generating APIs Without Writing Code (85)
    We now want to make an API so that other users can access our data in thier own apps.
    
    Model Your Domain, Derive the Results
        In this chapter we will build a REST and GraphQL API for other users to access our data.

    Building A JSON REST interface
        We will use some built in ASH package to generate the API that will accept requests over HTTP and the send the data in a JSON format

        Setup
            Lets add some features to the app. This will be done with and igniter install, here is what it will do: 
                ash_json_api Hex package
                Code formatting and configuration to support a new application/vnd.api+json
                New TunezWeb.AshJsonApiRouter
                A new scope for the Phoenix router.

                mix igniter.install ash_json_api

        Adding Artists to the API
            We will try and implement the CRUD for the API and as such we will need to add each resource and then make them public. We will use the extend Mix task to do so. A couple of things that this will do:
                AshJsonApi.Resource will be added to make use of the new access point
                A default API type will be added to the resource.
            Since it is the first resource for Music it will connect the pieces of the domain
                AshJsonApi.Domain will be added as an extension of the Tunez.Music domain
                Tunez.Music will be added to the list of domains in the TunezWeb.AshJsonApiRouter module.
                mix ash.extend Tunez.Music.Artist json_api

            Now we need to set some of the routes to make the actions on the Artist resource available in the API. We could add the domain or the resource to the API but it makes more sense to add a layer of obfiscation so that a user can only interact with the top layer of the domain. Head to lib/tunez/music.ex
                defmodule Tunez.Music do
                    # ...
                    json_api do
                            routes do
                            base_route "/artists", Tunez.Music.Artist do
                                get :read
                                index :search
                                post :create
                                patch :update
                                delete :destroy
                            end
                        end
                    end
                end
            
            This will set some default actions for each user for each artist. GET and artist POST will create an artist, and so on. We can check the routes from a the WSL console
                mix phx.routes

            You can even use the GET route by accessing http://localhost:4000/api/json/artists/?query=and

            "What Data Gets Included in API Responses?
                So you might notice that some of the data is missing and that is becuase only the attributes that are made public are included. This is a security thing and can be changed. Lets add the biography and the previous_names to the public list, head to lib/tunez/music/artist.ex
                    attributes do
                        # ...

                        attribute :previous_names, {:array, :string} do
                            default []
                            public? true
                        end

                        attribute :biography, :string do
                            public? true
                        end
                        # ...
                    end
            
                Calculations and Aggregates are different as they can be calculation expensive so there are a few ways to make them visible to the API:
                    Set them as default fields at the resource level. This will be done EVERYTIME that the resource is pulled. 
                    Make it so that a user can request the specific calculation or aggreagates that they require. They will need to add the field to the query string parameters. Something like http://localhost:4000/api/json/artists?fields=name,album_count . THis is a default response in the ASH framework.

            "Creating Artists Records"
                There is quite a few routes that were created and we will just go over the post but with the right body and route you can use the API to create an artist as well. 

                The PATCH can update and the DELETE can remove an artist.
        
        Adding Albums to the API
            We can use the same extension to add albums to the API as well. Afterwards we will need to add in the routes and default actions that we want the API route to be able to use.
                mix ash.extend Tunez.Music.Album json_api
            
            Now we need to head to lib/tunez/music.ex to add in the routes as we did before
                json_api do
                    routes do
                        # ...

                        base_route "/albums", Tunez.Music.Album do
                            post :create
                            patch :update
                            delete :destroy
                        end
                    end

            We now have the way to work with the albums but we don't have a nice way of dealing with the artist_id that is usually pre-hidden in the HTTP request. We will need to provide a valid ID for that and we will need to head into the album.ex to make those values public. Head to lib/tunez/music/album.ex to make those changes.
                attributes do
                    uuid_primary_key :id
                    attribute :name, :string do
                        allow_nil? false
                        public? true
                    end
                    attribute :year_released, :integer do
                        allow_nil? false
                        public? true
                    end
                    attribute :cover_image_url, :string do
                        public? true
                    end
                    # ...

            "Showing Albums for a Given Artist"
                There are to ways to include related resources for a given resource. Both will require that the relationship is public. Head to lib/tunez/music/artist.ex to set that now.
                    relationships do
                        has_many :albums, Tunez.Music.Album do
                            sort year_released: :desc
                            public? true
                        end
                    end

            "Including Related Records"
                The easist way and it mirrors the way we have done things like this before and that is to include it in the json_api parent resource. Like this http://localhost:4000/api/json/artists?query=cove&include=albums
                    json_api do
                        type "artist"
                        includes [:albums]
                    end
            
            "Linking to a List of Related Records"
                You can add a link the the records that the user might want wit the GET call to the API. This will require heading into lib/tunez/music.ex and adding in a related relationship to the API response.
                    base_route "/artists", Tunez.Music.Artist do
                        # ...
                        related(:albums, :read, primary?: true)
                    end
                    
        Generating API Documentation with OpenApiSpex
            The installation of AshJsonApi also incluced a way to build some Documentation with ease. We just need to add in the route. Head to lib/tunez_web/ash_json_api_router.ex to see what it already did. http://localhost:4000/api/json/open_api
                defmodule TunezWeb.AshJsonApiRouter do
                    use AshJsonApi.Router,
                        domains: [Tunez.Music],
                        open_api: "/open_api"
                end

            Now this is just a json result with all the information but not a clear way of using it you can use the built in funcionality of swaggerui to format it much better. Head to lib/tunez_web/router.ex this will made the route api/json/swaggerui available
                scope "/api/json" do
                    pipe_through [:api]

                    forward "/swaggerui", OpenApiSpex.Plug.SwaggerUI,
                    path: "/api/json/open_api",
                    default_model_expand_depth: 4

                    forward "/", TunezWeb.AshJsonApiRouter
                end

        Customizing the Generated API
            Lets tackle some low hanging fruit and make it look better and work better.
            
            "Adding Informative Descriptions"
                Ash allows us to set some descriptors for all the resources that we have in order to make any Documentation or calls be better understood.
                    A description for a resource as a whole. or
                    A description for an action or an argument for an action

                Take some time and add in a few of those here are some to get you started
                    defmodule Tunez.Music.Artist do
                        use Ash.Resource, ...
                        resource do
                            description "A person or group of people that makes and releases music."
                        end

                        read :search do
                            description "List Artists, optionally filtering by name."
                            argument :query, :ci_string do
                                description "Return only artists with names including the given value."
                                # ...

            "Updating the API Title and Version"
                Head to lib/tunez_web/ash_json_api_router.ex and then add some lines so that when you are using the route there is a title and version in the heading.
                    defmodule TunezWeb.AshJsonApiRouter do
                        use AshJsonApi.Router,
                            domains: [Tunez.Music],
                            open_api: "/open_api",
                            open_api_title: "Tunez API Documentation",
                            open_api_version: to_string(Application.spec(:tunez, :vsn))
                    end

            "Removing Unwanted Extras"
                If you took some time to look through the API docs you see that there is some filtering that we are not using as we have our own setup. You can disable the built in versions if you want and it is with the derive_filter? boolean flag. Head to tunez/music/artist.ex and add this line.
                    json_api do
                        type("artist")
                        includes([:albums])
                        derive_filter?(false)
                    end

    Building a GraphQL interface
        This is an other way to do the same things but this will do a few different things. We will go over those in the next section.

        Setup
            Using a similar igniter install we will be doing some different things:
                Code formatting and configuration for AshGraphql and Absinthe
                New graphql pipeline and scope for your Phoenix router, taking /gql and /gqp/playground
                New TunezWeb.GraphqlSchema
                New TunezWe.GraphqlSocket
            You can head to http://localhost:4000/gql/playground after we get it all setup.
                mix igniter.install ash_graphql

            This next bit will go fast as there is a lot that we have done that will look very similar
        
        Adding Artists to the API
            mix ash.extend Tunez.Music.Artist graphql

            We will now need to add in the queries and actions for the new API route. Head to lib/tunez/music.ex and add this new block.
                graphql do
                    queries do
                        get Tunez.Music.Artist, :get_artist_by_id, :read
                        list Tunez.Music.Artist, :search_artists, :search
                    end
                end

            This will create queries named getArtistById and searchArtistById that connects to the read action. We can now now add some non read options that will all be mutations, same file
                graphql do
                    # ...

                    mutations do
                    create Tunez.Music.Artist, :create_artist, :create
                    update Tunez.Music.Artist, :update_artist, :update
                    delete Tunez.Music.Artist, :destroy_artist, :destroy
                    end
                end

            "What Data Gets Included in API Responses?"
                We already did this in the previous section so this will not change anything

            "Creating Artist Records"
                Same as before this will not change.
        
        Adding Albums to the API
            We will use the same ash.extend but for graphql and albums then we will need to set the mutations for the graphql
                mix ash.extend Tunez.Music.Album graphql

            Then head to lib/tunez/music.ex
                graphql do
                    mutations do
                        # ...    
                
                        create Tunez.Music.Album, :create_album, :create
                        update Tunez.Music.Album, :update_album, :update
                        destroy Tunez.Music.Album, :destroy_album, :destroy
                    end
                end

            "Showing Albums for a Given Artist"
                Same as we did for the RESTful

        Customizing the Generated API
            Same as we did before we want to remove the unwanted fields it will be very similar but I will go over the needs for the graphql part

            "Removing Unwanted Extras"
                Here is where we will set the fields that will allows us to filter results, head to lib/tunez/music/artist.ex make these changes.
                    graphql do
                        type :artist
                        filterable_fields [:album_count, :cover_image_url, :inserted_at, :latest_album_year_released, :updated_at]
                    end

    That is it for this section hope you learned something.