github.com/onflow/flow-go@v0.35.7-crescendo-preview.23-atree-inlining/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 the server generator and the select filter, implementation of handling local requests.
    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  - `routes`: The common HTTP handlers for all the requests, tests for each request.
    14  - `apiproxy`: Implementation of proxy backend handler which includes the local backend and forwards the methods which 
    15  can't be handled locally to an upstream using gRPC API. This is used by observers that don't have all data in their
    16  local db.
    17  
    18  ## Request lifecycle
    19  
    20  1. Every incoming request passes through a common set of middlewares - logging middleware, query expandable and query
    21     select middleware defined in the middleware package.
    22  2. Each request is then wrapped by our handler (`rest/handler.go`) and request input data is used to build the request
    23     models defined in request package.
    24  3. The request is then sent to the corresponding API handler based on the configuration in the router.
    25  4. Each handler implements actions to perform the request (database lookups etc) and after the response is built using
    26     the model builders defined in models package.
    27  5. Returned value is then again handled by our wrapped handler making sure to correctly handle successful and failure
    28     responses.
    29  
    30  ## Maintaining
    31  
    32  ### Updating OpenAPI Schema
    33  
    34  Make sure the OpenAPI schema if first updated and merged into
    35  master [on the hosted repository](https://github.com/onflow/flow/tree/master/openapi). After you can use the make
    36  command to generated updated models:
    37  
    38  ```makefile
    39  make generate-openapi
    40  ```
    41  
    42  ### Adding New API Endpoints
    43  
    44  A new endpoint can be added by first implementing a new request handler, a request handle is a function in the routes
    45  package that complies with function interfaced defined as:
    46  
    47  ```go
    48  type ApiHandlerFunc func (
    49  r *request.Request,
    50  backend access.API,
    51  generator models.LinkGenerator,
    52  ) (interface{}, error)
    53  ```
    54  
    55  That handler implementation needs to be added to the `router.go` with corresponding API endpoint and method. If the data
    56  is not available on observers, an override the method is needed in the backend handler `RestProxyHandler` for request 
    57  forwarding. Adding a new API endpoint also requires for a new request builder to be implemented and added in request 
    58  package. Make sure to not forget about adding tests for each of the API handler.