github.com/koko1123/flow-go-1@v0.29.6/engine/access/rest/README.md (about)

     1  # Flow Access Node HTTP API Server
     2  
     3  This package and subpackages implement the HTTP API Server for
     4  the [Flow OpenAPI definition](https://github.com/onflow/flow/blob/master/openapi/access.yaml). The API documentation is
     5  available on our [docs site](https://docs.onflow.org/http-api/).
     6  
     7  ## Packages
     8  
     9  - `rest`: The HTTP handlers for all the request, server generator and the select filter.
    10  - `middleware`: The common [middlewares](https://github.com/gorilla/mux#middleware) that all request pass through.
    11  - `models`: The generated models using openapi generators and implementation of model builders.
    12  - `request`: Implementation of API requests that provide validation for input data and build request models.
    13  
    14  ## Request lifecycle
    15  
    16  1. Every incoming request passes through a common set of middlewares - logging middleware, query expandable and query
    17     select middleware defined in the middleware package.
    18  2. Each request is then wrapped by our handler (`rest/handler.go`) and request input data is used to build the request
    19     models defined in request package.
    20  3. The request is then sent to the corresponding API handler based on the configuration in the router.
    21  4. Each handler implements actions to perform the request (database lookups etc) and after the response is built using
    22     the model builders defined in models package.
    23  5. Returned value is then again handled by our wrapped handler making sure to correctly handle successful and failure
    24     responses.
    25  
    26  ## Maintaining
    27  
    28  ### Updating OpenAPI Schema
    29  
    30  Make sure the OpenAPI schema if first updated and merged into
    31  master [on the hosted repository](https://github.com/onflow/flow/tree/master/openapi). After you can use the make
    32  command to generated updated models:
    33  
    34  ```makefile
    35  make generate-openapi
    36  ```
    37  
    38  ### Adding New API Endpoints
    39  
    40  A new endpoint can be added by first implementing a new request handler, a request handle is a function in the rest
    41  package that complies with function interfaced defined as:
    42  
    43  ```go
    44  type ApiHandlerFunc func (
    45  r *request.Request,
    46  backend access.API,
    47  generator models.LinkGenerator,
    48  ) (interface{}, error)
    49  ```
    50  
    51  That handler implementation needs to be added to the `router.go` with corresponding API endpoint and method. Adding a
    52  new API endpoint also requires for a new request builder to be implemented and added in request package. Make sure to
    53  not forget about adding tests for each of the API handler.