1# Web API Base Template — REFERENCE ONLY
2 
3Default template for REST API workloads on Azure App Service. Use when no specific integration is detected or as the base for recipe composition.
4 
5## Templates by Runtime
6 
7| Runtime | AZD Template | Framework |
8|---------|-------------|-----------|
9| C# (.NET) | `azd init -t todo-csharp` | ASP.NET Core Minimal API |
10| Node.js (JS) | `azd init -t todo-nodejs-mongo` | Express.js |
11| Node.js (TS) | `azd init -t todo-nodejs-mongo` | Express.js (TypeScript) |
12| Python | `azd init -t todo-python-mongo` | FastAPI / Flask |
13| Java | `azd init -t todo-java-mongo` | Spring Boot |
14 
15**Browse all:** [Awesome AZD App Service](https://azure.github.io/awesome-azd/?tags=appservice)
16 
17> ⚠️ The AZD templates above include Mongo/Cosmos by default. When using as a pure Web API base, strip the database layer before applying a recipe:
18> - Remove `infra/app/db.bicep` (or equivalent database module)
19> - Remove Cosmos/Mongo module references from `infra/main.bicep`
20> - Remove Cosmos/Mongo packages from the application source
21>
22> Then apply the appropriate [recipe](recipes/README.md) for your data store.
23 
24## Project Structure
25 
26```
27project-root/
28├── azure.yaml              # AZD service config
29├── infra/
30│   ├── main.bicep           # Main orchestrator
31│   ├── main.parameters.json
32│   └── app/
33│       ├── web.bicep         # App Service + Plan
34│       └── web-network.bicep # VNet integration (conditional)
35└── src/
36    └── api/                  # Application source
37```
38 
39## App Service Plan Configuration
40 
41```bicep
42resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
43  name: '${name}-plan'
44  location: location
45  tags: tags
46  sku: {
47    name: 'B1'              // Dev/test — use P1v3+ for production
48  }
49  properties: {
50    reserved: true           // Required for Linux
51  }
52}
53```
54 
55| Environment | Recommended SKU | Notes |
56|-------------|----------------|-------|
57| Dev/Test | B1 | Basic tier, no autoscale |
58| Production | P1v3 | Premium v3, autoscale, VNet integration |
59| High-scale | P2v3 / P3v3 | Higher CPU/memory |
60 
61## Health Check Endpoint
62 
63> **CRITICAL**: Always include a health check endpoint. App Service uses it for instance monitoring.
64 
65Configure in App Service:
66```bicep
67properties: {
68  siteConfig: {
69    healthCheckPath: '/health'
70  }
71}
72```
73 
74### Health check by language
75 
76**C# (ASP.NET Core)**
77```csharp
78app.MapGet("/health", () => Results.Ok(new { status = "healthy" }));
79```
80 
81**Node.js (Express)**
82```javascript
83app.get('/health', (req, res) => {
84  res.json({ status: 'healthy' });
85});
86```
87 
88**Python (FastAPI)**
89```python
90@app.get("/health")
91async def health():
92    return {"status": "healthy"}
93```
94 
95**Java (Spring Boot)**
96```java
97@GetMapping("/health")
98public Map<String, String> health() {
99    return Map.of("status", "healthy");
100}
101```
102 
103## Dockerfile Reference
104 
105All App Service deployments can use container deployment. Each runtime should include a Dockerfile:
106 
107**Python (FastAPI)**
108```dockerfile
109FROM python:3.12-slim
110WORKDIR /app
111COPY requirements.txt .
112RUN pip install --no-cache-dir -r requirements.txt
113COPY . .
114EXPOSE 8000
115CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
116```
117 
118**Node.js**
119```dockerfile
120FROM node:20-slim
121WORKDIR /app
122COPY package*.json ./
123RUN npm ci --production
124COPY . .
125EXPOSE 3000
126CMD ["node", "src/index.js"]
127```
128 
129## App Settings (Managed Identity)
130 
131> 💡 Call `mcp_bicep_get_az_resource_type_schema` with resource type `Microsoft.Web/sites` to validate properties before generating this resource.
132 
133```bicep
134resource webApp 'Microsoft.Web/sites@2023-12-01' = {
135  properties: {
136    siteConfig: {
137      appSettings: [
138        { name: 'WEBSITE_HEALTHCHECK_MAXPINGFAILURES', value: '3' }
139        { name: 'SCM_DO_BUILD_DURING_DEPLOYMENT', value: 'true' }
140      ]
141    }
142  }
143  identity: {
144    type: 'UserAssigned'
145    userAssignedIdentities: {
146      '${managedIdentity.id}': {}
147    }
148  }
149  tags: {
150    'azd-service-name': 'api'
151  }
152}
153```
154 
155> ⚠️ **Without `azd-service-name` tag, `azd deploy` fails with:**
156> `resource not found: unable to find a resource tagged with 'azd-service-name: api'`
157>
158> The tag value must match the `services.<name>` key in `azure.yaml`. Use `api` for Web API services.
159 
160## Deployment
161 
162```bash
163ENV_NAME="$(basename "$PWD" | tr '[:upper:]' '[:lower:]' | tr ' _' '-')-dev"
164azd init -t <template> -e "$ENV_NAME" --no-prompt
165azd env set AZURE_LOCATION eastus2
166azd up --no-prompt
167```
168 
169**PowerShell:**
170```powershell
171$ENV_NAME = "$(Split-Path -Leaf (Get-Location) | ForEach-Object { $_.ToLower() -replace '[ _]','-' })-dev"
172azd init -t <template> -e $ENV_NAME --no-prompt
173azd env set AZURE_LOCATION eastus2
174azd up --no-prompt
175```
176 
177## References
178 
179- [App Service overview](https://learn.microsoft.com/en-us/azure/app-service/overview)
180- [App Service best practices](https://learn.microsoft.com/en-us/azure/app-service/app-service-best-practices)
181- [Health check](https://learn.microsoft.com/en-us/azure/app-service/monitor-instances-health-check)
182