API Documentation & Testing Tools

📚 Documentation Navigation

• ← Back to Main README - Overview and features
• ← Quick Start Guide - Setup instructions
• Field Query Guide → - Detailed field-level queries
• Testing Examples → - Practical code examples

---

Built-in Documentation Options

1. Swagger UI (Interactive API Documentation)

URL: https://reporting.api.myezrewards.com/swagger

Available in: Development mode

Features:

• Interactive API testing
• View all endpoints
• Test authentication
• See request/response schemas
• Try out queries directly in browser

How to Use:

1. Run the API: dotnet run
2. Navigate to https://reporting.api.myezrewards.com/swagger
3. Click "Authorize" button
4. Enter your apikey in the ApiKey field
5. Enter your JWT token in the Bearer field (without "Bearer" prefix)
6. Click "Authorize"
7. Try out any endpoint

Limitations:

• Standard Swagger doesn't provide OData query builder UI
• You'll need to manually construct OData queries in the URL

---

2. OData Metadata Endpoint (Standard OData Documentation)

URL: https://reporting.api.myezrewards.com/odata/$metadata

Available in: All environments

Features:

• Complete EDM (Entity Data Model) in XML format
• Lists all entity types and their properties
• Shows relationships between entities
• Describes navigation properties
• Standard OData format

Example Response:

<?xml version="1.0" encoding="utf-8"?>
<edmx:Edmx Version="4.0" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
  <edmx:DataServices>
    <Schema Namespace="EnduranceZone.Database" xmlns="http://docs.oasis-open.org/odata/ns/edm">
      <EntityType Name="RewardPartner">
        <Key>
          <PropertyRef Name="Id"/>
        </Key>
        <Property Name="Id" Type="Edm.Int64" Nullable="false"/>
        <Property Name="Name" Type="Edm.String"/>
        ...
      </EntityType>
    </Schema>
  </edmx:DataServices>
</edmx:Edmx>

How to Use:

• Open in browser with authentication headers
• Use tools like Postman or curl
• Import into OData client tools

---

3. OData Service Document

URL: https://reporting.api.myezrewards.com/odata/

Available in: All environments

Features:

• Lists all available entity sets
• JSON format
• Quick reference of endpoints

Example Response:

{
  "@odata.context": "https://reporting.api.myezrewards.com/odata/$metadata",
  "value": [
    {
      "name": "Partners",
      "kind": "EntitySet",
      "url": "Partners"
    },
    {
      "name": "Rewards",
      "kind": "EntitySet",
      "url": "Rewards"
    },
    ...
  ]
}

---

Recommended Tools for OData APIs

1. Postman (Best for Testing)

Setup:

1. Create new collection
2. Add environment variables:
   • baseUrl: https://reporting.api.myezrewards.com
   • apiKey: Your API key
   • bearerToken: Your JWT token
3. Set headers on collection level:
   • apikey: {{apiKey}}
   • Authorization: Bearer {{bearerToken}}

Benefits:

• Save and organize requests
• Environment variables
• Test automation
• Response visualization
• Collection sharing

Example Collection Structure:

Reporting API
├── Partners
│   ├── Get All Partners
│   ├── Get Partner by ID
│   ├── Filter Partners by Country
│   └── Search Partners
├── Rewards
│   ├── Get All Rewards
│   ├── Get Active Rewards
│   └── Filter by Country
└── Tracking
    ├── Get Activities
    ├── Get Logins
    └── Get Impressions

---

2. OData Explorer (Browser Extension)

Chrome Extension: "OData Explorer"

Features:

• Visual query builder
• Browse entity sets
• Build filters visually
• See relationships
• Generate query URLs

---

3. LINQPad (For .NET Developers)

URL: https://www.linqpad.net/

Features:

• Connect directly to OData services
• Write LINQ queries
• IntelliSense support
• Result visualization

Example:

var context = new Container(new Uri("https://reporting.api.myezrewards.com/odata"));
context.SendingRequest2 += (s, e) => {
    e.RequestMessage.SetHeader("apikey", "your-api-key");
    e.RequestMessage.SetHeader("Authorization", "Bearer your-token");
};

var partners = context.Partners
    .Where(p => p.IsActive == true)
    .OrderBy(p => p.Name)
    .Take(10);

---

4. REST Client (VS Code Extension)

Extension: "REST Client" by Huachao Mao

Create file: api-tests.http

Example:

### Variables
@baseUrl = https://reporting.api.myezrewards.com
@apiKey = your-api-key-here
@bearerToken = your-jwt-token-here

### Get Token (exchange API key once)
GET {{baseUrl}}/api/authentication/getauthtoken
apikey: {{apiKey}}

### Get Partners
GET {{baseUrl}}/odata/Partners
Authorization: Bearer {{bearerToken}}

### Get Users with Filter
GET {{baseUrl}}/odata/Users?$filter=IsActive eq true
Authorization: Bearer {{bearerToken}}

### Get Tracking Activities
GET {{baseUrl}}/odata/TrackingActivities?$top=50&$orderby=CreatedAt desc
Authorization: Bearer {{bearerToken}}

---

Quick Reference: Available Endpoints

When API is Running

Swagger UI:

https://reporting.api.myezrewards.com/swagger

OData Metadata:

https://reporting.api.myezrewards.com/odata/$metadata

OData Service Document:

https://reporting.api.myezrewards.com/odata/

Entity Sets:

https://reporting.api.myezrewards.com/odata/Partners
https://reporting.api.myezrewards.com/odata/PartnerCategories
https://reporting.api.myezrewards.com/odata/Rewards
https://reporting.api.myezrewards.com/odata/RewardCountries
https://reporting.api.myezrewards.com/odata/RewardBrands
https://reporting.api.myezrewards.com/odata/TrackingActivities    (Elasticsearch-backed)
https://reporting.api.myezrewards.com/odata/TrackingLogins         (Elasticsearch-backed)
https://reporting.api.myezrewards.com/odata/TrackingImpressions
https://reporting.api.myezrewards.com/odata/Users
https://reporting.api.myezrewards.com/odata/UsersElastic           (Elasticsearch-backed)

REST Endpoints:

https://reporting.api.myezrewards.com/api/authentication/getauthtoken
https://reporting.api.myezrewards.com/api/users/counts
https://reporting.api.myezrewards.com/api/users/cohorts
https://reporting.api.myezrewards.com/api/users/segments
https://reporting.api.myezrewards.com/api/users/elastic
https://reporting.api.myezrewards.com/api/cache/clear

---

Testing Workflow

Step 1: Start the API

cd C:\dev\Api\Reporting.Api\Reporting.Api
dotnet run

Step 2: Open Swagger

Navigate to: https://reporting.api.myezrewards.com/swagger

Step 3: Authenticate

1. Click "Authorize" button (top right)
2. Enter API Key in "ApiKey" section
3. Enter JWT token in "Bearer" section
4. Click "Authorize"

Step 4: Test Endpoints

• Expand any endpoint
• Click "Try it out"
• Modify parameters if needed
• Click "Execute"
• View response

Step 5: Build OData Queries

Use the endpoint URL and add OData query parameters:

/odata/Partners?$filter=IsActive eq true&$select=Id,Name&$top=20

---

OData Query Cheat Sheet

Filter Operators

eq  - Equal                    : $filter=Id eq 123
ne  - Not equal               : $filter=Id ne 123
gt  - Greater than            : $filter=CreatedAt gt 2024-01-01
ge  - Greater than or equal   : $filter=CreatedAt ge 2024-01-01
lt  - Less than               : $filter=CreatedAt lt 2024-12-31
le  - Less than or equal      : $filter=CreatedAt le 2024-12-31
and - Logical and             : $filter=Id eq 123 and IsActive eq true
or  - Logical or              : $filter=Type eq 'click' or Type eq 'view'
not - Logical not             : $filter=not (IsActive eq false)

String Functions

contains    : $filter=contains(Name,'fitness')
startswith  : $filter=startswith(Name,'Gold')
endswith    : $filter=endswith(Name,'Gym')
tolower     : $filter=tolower(Name) eq 'gold gym'
toupper     : $filter=toupper(Name) eq 'GOLD GYM'

Query Options

$select     : Choose fields           : $select=Id,Name
$filter     : Filter results          : $filter=IsActive eq true
$orderby    : Sort results            : $orderby=CreatedAt desc
$top        : Limit results           : $top=20
$skip       : Skip results            : $skip=40
$count      : Include count           : $count=true
$expand     : Include related data    : $expand=Partner

---

Documentation Best Practices

1. Always check Swagger first - It's the easiest way to explore the API
2. Use $metadata for schema details - When you need exact property types
3. Save common queries in Postman - Build a collection for your team
4. Test incrementally - Start simple, add complexity
5. Check response structure - OData wraps results in value array

---

Troubleshooting Documentation Access

Swagger Not Loading

• Ensure running in Development mode
• Check ASPNETCORE_ENVIRONMENT=Development
• Verify URL: https://reporting.api.myezrewards.com/swagger

401 on Metadata Endpoint

• Metadata endpoint requires authentication
• Add apikey and Authorization headers
• Use Postman or curl with headers

Can't See Entity Properties

• Check $metadata endpoint
• Verify entity is in OData model (Program.cs)
• Check database connection

---

Additional Resources

• OData Documentation: https://www.odata.org/documentation/
• OData Query Tutorial: https://www.odata.org/getting-started/basic-tutorial/
• Swagger Documentation: https://swagger.io/docs/
• Postman Learning: https://learning.postman.com/

---

Summary

For Interactive Testing: Use Swagger UI at /swagger

• Best for quick testing and exploration
• Visual interface
• No additional tools needed

For OData Schema: Use $metadata endpoint

• Complete entity model
• Standard OData format
• Can be imported into tools

For Production Use: Use Postman or REST Client

• Save and organize requests
• Team collaboration
• Automated testing

All three options are available when you run the API!

---

📚 Related Documentation

• ← Back to Main README - Overview and features
• ← Quick Start Guide - Setup instructions
• Field Query Guide → - Detailed field queries for each endpoint
• Testing Examples → - PowerShell, curl, and C# examples