fix api page issues and missing examples

Author: jyecusch

docs/apis.mdx

@@ -83,10 +83,30 @@ myApi.get("/hello", (ctx) async {
 
 Each API in your application needs a unique name. This name is used to identify the API across your project and in cloud deployments.
 
-```javascript
+<CodeSwitcher tabs>
+
+```javascript !!
+const myApi = api('my-api-name')
+```
+
+```typescript !!
 const myApi = api('my-api-name')
 ```
 
+```python !!
+my_api = api('my-api-name')
+```
+
+```go !!
+myApi := nitric.NewApi("my-api-name")
+```
+
+```dart !!
+final myApi = Nitric.api("my-api-name");
+```
+
+</CodeSwitcher>
+
 ### Request Context
 
 Every handler receives a context object (`ctx`) that contains:
@@ -417,6 +437,10 @@ final secureApi = Nitric.api(
 
 You can configure custom domains for your APIs in your stack configuration:
 
+<Tabs>
+
+<TabItem label="AWS">
+
 ```yaml title:nitric.prod.yaml
 provider: nitric/[email protected]
 region: us-east-1
@@ -427,10 +451,30 @@ apis:
       - api.example.com
 ```
 
+</TabItem>
+
+<TabItem label="Azure">
+
+```yaml title:nitric.prod.yaml
+# Currently unsupported - request support here: https://github.com/nitrictech/nitric/issues
+```
+
+</TabItem>
+
+<TabItem label="GCP">
+
+```yaml title:nitric.prod.yaml
+# Currently unsupported - request support here: https://github.com/nitrictech/nitric/issues
+```
+
+</TabItem>
+
+</Tabs>
+
 <Note>
   Custom domains are currently only supported for AWS deployments. See the [AWS
-  Custom Domain Prerequisites](#aws-custom-domain-prerequisites) section for
-  setup details.
+  Custom Domain Setup](/providers/mappings/aws/apis#custom-domain-prerequisites)
+  section for setup details.
 </Note>
 
 ## Project Organization
@@ -439,7 +483,19 @@ apis:
 
 You can split your API routes across multiple services while using the same API resource:
 
-```javascript title:services/users.js
+<CodeSwitcher tabs>
+
+```javascript !! title:services/users.js
+import { api } from '@nitric/sdk'
+
+const myApi = api('my-api')
+
+myApi.get('/users', async (ctx) => {
+  // Handle user listing
+})
+```
+
+```typescript !! title:services/users.ts
 import { api } from '@nitric/sdk'
 
 const myApi = api('my-api')
@@ -449,7 +505,65 @@ myApi.get('/users', async (ctx) => {
 })
 ```
 
-```javascript title:services/products.js
+```python !! title:services/users.py
+from nitric.resources import api
+from nitric.application import Nitric
+
+my_api = api('my-api')
+
+@my_api.get("/users")
+async def list_users(ctx):
+    // Handle user listing
+    pass
+
+Nitric.run()
+```
+
+```go !! title:services/users/main.go
+package main
+
+import (
+  "github.com/nitrictech/go-sdk/nitric"
+  "github.com/nitrictech/go-sdk/nitric/apis"
+)
+
+func main() {
+  myApi := nitric.NewApi("my-api")
+
+  myApi.Get("/users", func(ctx *apis.Ctx) {
+    // Handle user listing
+  })
+
+  nitric.Run()
+}
+```
+
+```dart !! title:services/users.dart
+import 'package:nitric_sdk/nitric.dart';
+
+final myApi = Nitric.api("my-api");
+
+myApi.get("/users", (ctx) async {
+  // Handle user listing
+  return ctx;
+});
+```
+
+</CodeSwitcher>
+
+<CodeSwitcher tabs>
+
+```javascript !! title:services/products.js
+import { api } from '@nitric/sdk'
+
+const myApi = api('my-api')
+
+myApi.get('/products', async (ctx) => {
+  // Handle product listing
+})
+```
+
+```typescript !! title:services/products.ts
 import { api } from '@nitric/sdk'
 
 const myApi = api('my-api')
@@ -459,26 +573,160 @@ myApi.get('/products', async (ctx) => {
 })
 ```
 
+```python !! title:services/products.py
+from nitric.resources import api
+from nitric.application import Nitric
+
+my_api = api('my-api')
+
+@my_api.get("/products")
+async def list_products(ctx):
+    // Handle product listing
+    pass
+
+Nitric.run()
+```
+
+```go !! title:services/products/main.go
+package main
+
+import (
+  "github.com/nitrictech/go-sdk/nitric"
+  "github.com/nitrictech/go-sdk/nitric/apis"
+)
+
+func main() {
+  myApi := nitric.NewApi("my-api")
+
+  myApi.Get("/products", func(ctx *apis.Ctx) {
+    // Handle product listing
+  })
+
+  nitric.Run()
+}
+```
+
+```dart !! title:services/products.dart
+import 'package:nitric_sdk/nitric.dart';
+
+final myApi = Nitric.api("my-api");
+
+myApi.get("/products", (ctx) async {
+  // Handle product listing
+  return ctx;
+});
+```
+
+</CodeSwitcher>
+
 ### Shared Resources
 
 For better organization, you can define shared API resources:
 
-```javascript title:resources/api.js
+<CodeSwitcher tabs>
+
+```javascript !! title:resources/api.js
+import { api } from '@nitric/sdk'
+
+export const myApi = api('my-api')
+```
+
+```typescript !! title:resources/api.ts
 import { api } from '@nitric/sdk'
 
 export const myApi = api('my-api')
 ```
 
+```python !! title:resources/api.py
+from nitric.resources import api
+
+my_api = api('my-api')
+```
+
+```go !! title:resources/api/main.go
+package api
+
+import (
+  "github.com/nitrictech/go-sdk/nitric"
+  "github.com/nitrictech/go-sdk/nitric/apis"
+)
+
+var MyApi apis.Api
+
+func init() {
+  MyApi = nitric.NewApi("my-api")
+}
+```
+
+```dart !! title:resources/api.dart
+import 'package:nitric_sdk/nitric.dart';
+
+final myApi = Nitric.api("my-api");
+```
+
+</CodeSwitcher>
+
 Then import and use them in your services:
 
-```javascript title:services/users.js
+<CodeSwitcher tabs>
+
+```javascript !! title:services/users.js
+import { myApi } from '../resources/api'
+
+myApi.get('/users', async (ctx) => {
+  // Handle user listing
+})
+```
+
+```typescript !! title:services/users.ts
 import { myApi } from '../resources/api'
 
 myApi.get('/users', async (ctx) => {
   // Handle user listing
 })
 ```
 
+```python !! title:services/users.py
+from nitric.application import Nitric
+from resources.api import my_api
+
+@my_api.get("/users")
+async def list_users(ctx):
+    // Handle user listing
+    pass
+
+Nitric.run()
+```
+
+```go !! title:services/users/main.go
+package main
+
+import (
+  "your-project/resources/api"
+  "github.com/nitrictech/go-sdk/nitric"
+  "github.com/nitrictech/go-sdk/nitric/apis"
+)
+
+func main() {
+  api.MyApi.Get("/users", func(ctx *apis.Ctx) {
+    // Handle user listing
+  })
+
+  nitric.Run()
+}
+```
+
+```dart !! title:services/users.dart
+import '../resources/api.dart';
+
+myApi.get("/users", (ctx) async {
+  // Handle user listing
+  return ctx;
+});
+```
+
+</CodeSwitcher>
+
 ## Cloud Provider Support
 
 Each cloud provider has specific features and limitations for API deployments:

docs/providers/mappings/aws/apis.mdx

@@ -28,3 +28,32 @@ During deployment the Nitric CLI builds your API's routes, methods and handlers:
 - Lambda ARNs are injected into the API definition using the [x-amazon-apigateway-integration object](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration.html), creating an [API Gateway Integration](https://docs.aws.amazon.com/apigateway/api-reference/resource/integration/) for each.
 - The API definition is deployed as an API Gateway v2 HTTP API, using the `$default` stage name
 - IAM policies are created enabling API Gateway to execute the Lambdas
+
+### Custom Domain Prerequisites
+
+To support custom domains with APIs deployed to AWS your domain (or subdomain) will need to be setup as a [hosted zone](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-working-with.html) in Route 53.
+
+The general steps to setup a hosted zone in Route 53 are as follows:
+
+1. Navigate to Route 53 in the AWS Console
+2. Select 'hosted zones' from the left navigation
+3. Click 'Create hosted zone'
+4. Enter your domain name and choose the 'Public hosted zone' type.
+5. Click 'Create hosted zone'
+6. You will now be provided with a set of NS DNS records to configure in the DNS provider for your domain
+7. Create the required DNS records, then wait for the DNS changes to propagate
+
+Once this is done you will be able to use the hosted zone domain or any direct subdomain with your Nitric APIs.
+
+You can read more about how AWS suggests configuring hosted zones in their documentation on [Making Route 53 the DNS service for a domain that's in use](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/migrate-dns-domain-in-use.html) or [Making Route 53 the DNS service for an inactive domain](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/migrate-dns-domain-inactive.html).
+
+<Note>
+  If the hosted zone was nitric.io, nitric.io or api.nitric.io would be
+  supported for APIs, but not public.api.nitric.io since that is a subdomain of
+  a subdomain.
+</Note>
+
+<Note>
+  DNS propagation of the NS records can take a few seconds to a few hours due to
+  the nature of DNS.
+</Note>