Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:

.NET 9.0 SDK

Download

PostgreSQL

Version 12 or higher

Git

For cloning the repository
You can verify your .NET installation by running dotnet --version in your terminal.

​
Quick Setup

1

Clone the Repository

Clone the XGP Photo API repository to your local machine:
git clone <repository-url>
cd xgp-photo-api
2

Configure PostgreSQL Connection

Update the database connection string in appsettings.json:
appsettings.json
{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Port=5432;Database=XgpPhotoDb;Username=postgres;Password=yourPassword"
  }
}
Make sure PostgreSQL is running and the credentials match your local setup.
3

Configure JWT Settings

Update the JWT configuration in appsettings.json with your own secure key:
appsettings.json
{
  "Jwt": {
    "Issuer": "XgpPhotoApi",
    "Audience": "XgpPhotoClients",
    "Key": "your-super-secret-key-min-32-chars",
    "ExpMinutes": 60
  }
}
The JWT key should be at least 32 characters for HMACSHA256 security.
4

Configure Client Credentials

Set up your client application credentials in appsettings.json:
appsettings.json
{
  "AuthClients": [
    {
      "ClientId": "xgp-web",
      "ClientSecret": "Y0urCl13ntS3cret!2025",
      "Description": "Frontend Web principal"
    },
    {
      "ClientId": "xgp-mobile",
      "ClientSecret": "Mob1leAppS3cret@2025",
      "Description": "Mobile application"
    }
  ]
}
Change these default secrets before deploying to production.
5

Restore Dependencies

Restore all NuGet packages:
dotnet restore
6

Run the Application

Start the API server:
dotnet run
You should see output indicating:
🏗️ Aplicando migraciones...
✅ Migraciones aplicadas correctamente.
👑 Usuario administrador creado: [email protected]
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5000
7

Access Swagger Documentation

Open your browser and navigate to:
http://localhost:5000/swagger
You’ll see the interactive Swagger UI with all available endpoints.
Swagger is only available in Development mode for security reasons.

​
Your First API Request

Let’s make your first authenticated request to the API.

​
Step 1: Obtain a JWT Token

Authenticate using the default admin credentials: 
curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "XgpPhoto!2025$Secure",
    "clientId": "xgp-web",
    "clientSecret": "Y0urCl13ntS3cret!2025"
  }'
Response: 
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiration": "2026-03-04T18:30:00Z"
}
The token is valid for 60 minutes by default. Save this token for subsequent requests.

​
Step 2: Create Your First Project

Use the JWT token to create a photography project: 
curl -X POST http://localhost:5000/api/projects \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "title": "Summer Wedding Collection",
    "description": "Beautiful outdoor wedding photography",
    "imageUrl": "https://example.com/banner.jpg",
    "bannerClickTitle": "View Full Gallery",
    "bannerClickDescription": "Explore 50+ stunning photos",
    "isActive": true,
    "details": [
      {
        "imageUrl": "https://example.com/photo1.jpg",
        "isActive": true
      },
      {
        "imageUrl": "https://example.com/photo2.jpg",
        "isActive": true
      }
    ]
  }'
Replace YOUR_TOKEN_HERE with the actual JWT token received from the login endpoint.

​
Step 3: Retrieve Projects

Fetch all active projects (no authentication required): 
curl http://localhost:5000/api/projects
Response: 
[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "title": "Summer Wedding Collection",
    "description": "Beautiful outdoor wedding photography",
    "imageUrl": "https://example.com/banner.jpg",
    "bannerClickTitle": "View Full Gallery",
    "bannerClickDescription": "Explore 50+ stunning photos",
    "createDate": "2026-03-04T17:30:00Z",
    "modifiedDate": null,
    "isActive": true,
    "details": [
      {
        "id": "4fa85f64-5717-4562-b3fc-2c963f66afa7",
        "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "imageUrl": "https://example.com/photo1.jpg",
        "isActive": true,
        "createDate": "2026-03-04T17:30:00Z",
        "modifiedDate": null
      },
      {
        "id": "5fa85f64-5717-4562-b3fc-2c963f66afa8",
        "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "imageUrl": "https://example.com/photo2.jpg",
        "isActive": true,
        "createDate": "2026-03-04T17:30:00Z",
        "modifiedDate": null
      }
    ]
  }
]

​
Database Management

​
View Database Tables

Connect to your PostgreSQL database to verify the setup: 
psql -U postgres -d XgpPhotoDb

-- List all tables
\dt

-- View projects
SELECT * FROM "Projects";

-- View project details
SELECT * FROM "ProjectDetails";

-- View users
SELECT * FROM "AspNetUsers";

​
Reset Database

If you need to reset the database: 
# Drop the database
dropdb -U postgres XgpPhotoDb

# Restart the application - it will recreate everything
dotnet run
This will permanently delete all data. Use with caution.

​
Development Tips

Use dotnet watch run for automatic reload during development:
dotnet watch run
The application will automatically restart when you modify source files.
Logs are written to the console by default. Adjust logging levels in appsettings.json:
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.EntityFrameworkCore": "Information"
    }
  }
}
Use Swagger UI for interactive testing:
  1. Navigate to http://localhost:5000/swagger
  2. Click “Authorize” button
  3. Enter: Bearer YOUR_TOKEN
  4. Click “Authorize” to save
  5. Test endpoints directly from the UI
Add more client credentials in appsettings.json:
{
  "AuthClients": [
    {
      "ClientId": "my-app",
      "ClientSecret": "MyAppSecret123!",
      "Description": "My custom application"
    }
  ]
}
Restart the API after modifying configuration.

​
Troubleshooting

Error: Connection refused or password authentication failedSolution:
  • Verify PostgreSQL is running: systemctl status postgresql (Linux) or check Services (Windows)
  • Check connection string credentials match your PostgreSQL setup
  • Ensure PostgreSQL is listening on port 5432: netstat -an | grep 5432
Error: A connection was successfully established, but an error occurred during the login processSolution:
  • Delete the Migrations folder
  • Drop the database: dropdb -U postgres XgpPhotoDb
  • Run the application again to recreate migrations
Error: 401 Unauthorized when making authenticated requestsSolution:
  • Verify the token hasn’t expired (60 minute default)
  • Ensure you’re including the Bearer prefix: Authorization: Bearer YOUR_TOKEN
  • Check that the JWT Key in appsettings.json matches between login and validation
Error: Unauthorized: Invalid client credentialsSolution:
  • Verify ClientId and ClientSecret match exactly what’s in appsettings.json
  • Check for typos and ensure case sensitivity
  • Restart the API after modifying client credentials

​
Next Steps

Now that you have the API running, explore these topics:

Authentication Guide

Learn about JWT tokens and client validation

API Reference

Detailed documentation of all endpoints

Working with Projects

Understanding project management and data models

Deployment

Deploy to production environments

Build docs developers (and LLMs) love

Get started for freeTalk to us