Skip to content

APIView

Jump to bottom
Alitzel Mendez edited this page Jul 11, 2025 · 15 revisions

Getting Started with APIView Development

This guide helps Microsoft-internal contributors get up and running with APIView development. It covers project structure, setup steps, and contribution workflows for the ASP.NET backend and Angular frontend.

✅ You do not need to provision Azure resources.
⚠️ This guide assumes access to the existing APIView environment and the Azure SDK organization.

🔧 Project Overview

Project Description
APIView Core functionality (used by backend and C# parser)
APIViewWeb ASP.NET Core backend with all API endpoints and auth logic
ClientSPA Angular-based Single Page Application UI (served from spa.apiview.dev)

🥪 Testing

Test Project Status Notes
ApiViewUnitTests ✅ Active Covers API logic and backend functionality
Angular Unit Tests ✅ Active Run with ng test; lives in .spec.ts files
APIViewIntegrationTests ❌ Obsolete Required Cosmos & Storage emulators. Can likely be deleted.
APIViewUITests ❌ Obsolete Selenium-based, now obsolete. Angular has its own test suite.

💠 Prerequisites

You must be part of the Azure SDK GitHub organization and have the following tools installed:

  • Visual Studio (for backend development)
  • VS Code or terminal (for frontend)
  • Node.js
  • Angular CLI

🔑 Permissions

Run the following script to grant the required RBAC roles (Storage, Cosmos DB, App Config):

APIViewWeb/get-permissions.ps1

You'll need:

  • Your Microsoft email ([email protected])
  • Your user principal (az ad signed-in-user show)

🔐 Configure Secrets

  1. Right-click on APIViewWeb → Manage User Secrets
  2. Insert the following JSON (replace placeholder values):
{
  "AppConfigUrl": "https://<your-app-config>.azconfig.io",
  "Github:ClientId": "<YOUR_CLIENT_ID>",
  "Github:ClientSecret": "<YOUR_CLIENT_SECRET>",
  "APIVIew-Host-Url": "http://localhost:5000",
  "APIVIew-SPA-Host-Url": "https://localhost:4200"
}

Secrets and service connections will be loaded automatically via App Configuration and Key Vault.

🧭 Create a GitHub OAuth App (for local login)

  1. Go to GitHub → Settings → Developer Settings → OAuth Apps
  2. Click “New OAuth App”
  3. Fill in:
    • App name: APIViewLocal
    • Homepage URL: http://localhost:5000
    • Authorization callback URL: http://localhost:5000
  4. After creation, copy the Client ID and Secret into your User Secrets (see above)

▶️ Running Locally

1. Build Frontend Assets

cd src\dotnet\APIView\APIViewWeb\Client
npm install
npm run-script build

2. Start Backend

  • Open APIViewWeb in Visual Studio
  • Press F5

3. Run Frontend Dev Server (optional for hot reload)

cd src\dotnet\APIView\ClientSPA
npm install
npm run-script build
ng serve --ssl

🔁 Backend changes may require restarting the server
✅ Hot reload works automatically for Angular

🔐 Authentication Model

  • Uses cookie-based login
  • Cookies are valid across both localhost:5000 and localhost:4200
  • Look for [AllowAnonymous] attributes to identify public endpoints

🥚 Verifying Your Setup

You can test your local environment using an existing API review:

  1. Launch the app and log in via GitHub OAuth
  2. You should see the review list from staging
  3. Upload any valid token file or language-specific package to test upload

💡 Tips for Development

  • Use Swagger UI to explore backend endpoints
  • All Angular-visible APIs live in LeanControllers and use LeanModels
  • Public API access is marked with [AllowAnonymous]
  • Secrets and connections are managed via AppConfig + Key Vault

✅ Making Contributions

Where Should I Make Changes?

Area Modify If...
Backend (APIViewWeb) You're changing API logic, endpoints, or auth
Frontend (ClientSPA) You're updating UI components or views
APIView (core) You're modifying backend functionality shared across components

You do not need to modify or run language parsers (C#, Java, Python, etc.)

Testing Your Changes

  • Backend: Start Visual Studio debugger and verify functionality
  • Frontend: Use ng serve for live preview; run ng test for unit tests
  • Swagger: Use the built-in UI to test endpoints manually

Submitting a PR

  1. Create a branch from main
  2. Make and test your changes
  3. Open a PR via GitHub
  4. The CLA bot will validate your contributor status (first-time only)
  5. Tag reviewers or your team lead as needed

👥 Contacts

Name Email Notes
Travis Prescott [email protected] Current Dev
Alitzel Medez [email protected] Current Dev
Dozie Ononiwu [email protected] Prior Dev
Praveen Kuttappan [email protected] Prior Dev

For additional documentation, visit:
🔗 Internal Wiki

Clone this wiki locally