github.com/micro/go-micro/examples@v0.0.0-20210105173217-bf4ab679e18b/api/README.md (about)

     1  # API
     2  
     3  This repo contains examples for using the micro api.
     4  
     5  ## Overview
     6  
     7  The [micro api](https://github.com/micro/micro/tree/master/api) is an API gateway which serves HTTP and routes dynamically based on service discovery.
     8  
     9  The micro api by default serves the namespace go.micro.api. Our service names include this plus a unique name e.g go.micro.api.example. 
    10  You can change the namespace via the flag `--namespace=`.
    11  
    12  The micro api has a number of different handlers which lets you define what kind of API services you want. See examples below. The handler 
    13  can be set via the flag `--handler=`. The default handler is "rpc".
    14  
    15  ## Contents
    16  
    17  - api - an rpc handler that provides the entire http headers and request
    18  - proxy - use the api as a http reverse proxy
    19  - rpc - make an rpc request to a go-micro app
    20  - meta - specify which handler to use via configuration in code
    21  
    22  ## Request Mapping
    23  
    24  ### API/RPC
    25  
    26  Micro maps http paths to rpc services. The mapping table can be seen below.
    27  
    28  The default namespace for the api is **go.micro.api** but you can set your own namespace via `--namespace`.
    29  
    30  URLs are mapped as follows:
    31  
    32  Path	|	Service	|	Method
    33  ----	|	----	|	----
    34  /foo/bar	|	go.micro.api.foo	|	Foo.Bar
    35  /foo/bar/baz	|	go.micro.api.foo	|	Bar.Baz
    36  /foo/bar/baz/cat	|	go.micro.api.foo.bar	|	Baz.Cat
    37  
    38  Versioned API URLs can easily be mapped to service names:
    39  
    40  Path	|	Service	|	Method
    41  ----	|	----	|	----
    42  /foo/bar	|	go.micro.api.foo	|	Foo.Bar
    43  /v1/foo/bar	|	go.micro.api.v1.foo	|	Foo.Bar
    44  /v1/foo/bar/baz	|	go.micro.api.v1.foo	|	Bar.Baz
    45  /v2/foo/bar	|	go.micro.api.v2.foo	|	Foo.Bar
    46  /v2/foo/bar/baz	|	go.micro.api.v2.foo	|	Bar.Baz
    47  
    48  ### Proxy Mapping
    49  
    50  Starting the API with `--handler=http` will reverse proxy requests to backend services within the served API namespace (default: go.micro.api). 
    51  
    52  Example
    53  
    54  Path	|	Service	|	Service Path
    55  ---	|	---	|	---
    56  /greeter	|	go.micro.api.greeter	|	/greeter
    57  /greeter/:name	|	go.micro.api.greeter	|	/greeter/:name