REST Lens

REST Lens helps you validate OpenAPI specifications against REST API best practices using automated static analysis.

Quick Start

1. Create an Account

Visit restlens.com
Click "Sign Up" or "Get Started"
Choose your authentication method:
- Email + Password
- GitHub OAuth
- Google OAuth
Verify your email (if using email authentication)

2. Create an Organization

Organizations group related projects together and allow team collaboration.

After signing in, click "Create Organization"
Enter an organization name (e.g., "Acme Corp")
Choose a unique slug (e.g., "acme-corp")
- This will be part of your project URLs
- Can only contain lowercase letters, numbers, and hyphens
Click "Create Organization"

Note: You can create multiple organizations or join existing ones via invitations.

3. Create Your First Project

Projects contain your OpenAPI specifications and evaluation results.

Navigate to your organization page
Click "New Project"
Fill in the project details:
- Name: Human-readable name (e.g., "Payment API")
- Slug: URL-friendly identifier (e.g., "payment-api")
- Description (optional): Brief description of your API
Click "Create Project"

4. Upload an OpenAPI Specification

Via Web Interface

Go to your project page
Click "Upload" or drag and drop your file
Select your OpenAPI specification file:
- Supported formats: JSON (.json) or YAML (.yaml, .yml)
- Maximum size: 50MB
(Optional) Add a version tag (e.g., "v1.0.0" or a git commit hash)
The specification will be automatically evaluated

Via Command Line

curl -X POST \
  https://restlens.com/api/projects/[org]/[project]/specifications \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/x-yaml" \
  --data-binary @openapi.yaml

See the API Integration Guide for more details.

5. Review Results

After uploading, REST Lens automatically evaluates your specification:

Overview: See total violations and overall health score
Violations by Path: Browse violations organized by API endpoint
Violations by Rule: See which rules are being violated most
Severity Breakdown: View errors, warnings, and info messages

Understanding Results

Error 🔴: Significant design issues that should be fixed
Warning ⚠️: Best practices that improve quality
Info ℹ️: Suggestions and recommendations

Each violation includes:

Rule name and ID (click for detailed explanation)
Specific location in your specification
Why it matters
How to fix it

6. Configure Rules (Optional)

Customize which rules apply to your project:

Go to your project page
Click "Rules" in the navigation
For each rule, you can:
- Enable/Disable: Turn rules on or off
- Change Severity: Set to Error, Warning, or Info
- Configure Options: Some rules have configurable parameters
- Ignore Violations: Suppress specific false positives

Organization-Level Rules

Administrators can set default rules for all projects in an organization:

Go to your organization page
Click "Rules"
Configure default settings
Lock settings to enforce them across all projects

Common Workflows

Continuous Validation in CI/CD

Integrate REST Lens into your CI/CD pipeline to validate specs on every commit:

# GitHub Actions example
- name: Validate API Spec
  run: |
    curl -X POST \
      https://restlens.com/api/projects/my-org/my-project/specifications \
      -H "Authorization: Bearer ${{ secrets.RESTLENS_API_TOKEN }}" \
      -H "Content-Type: application/x-yaml" \
      --data-binary @openapi.yaml

See the full API Integration Guide for GitHub Actions, GitLab CI, and Jenkins examples.

Tracking Changes Over Time

Use version tags when uploading specs:
```
-H "X-Spec-Tag: ${GIT_COMMIT_SHA}"
```
View specification history in your project
Compare versions to see improvements or regressions
Track violation trends over time

Team Collaboration

Invite Team Members

Go to your organization settings
Click "Members" → "Invite Member"
Enter their email and select a role:
- Owner: Full access to all organization settings
- Admin: Manage projects and members
- Member: View and edit projects
They'll receive an email invitation

Share Results

Project URLs are shareable with team members
Use tags to identify specific versions
Add comments and ignore violations with context

Best Practices

Specification Management

Version your specs: Use git to track OpenAPI specification changes
Tag releases: Apply meaningful tags (e.g., semantic versions, git SHAs)
Automate uploads: Integrate with CI/CD for continuous validation
Review regularly: Check results after each change

Rule Configuration

Start with defaults: Use the default rule set initially
Customize gradually: Adjust rules based on your team's needs
Document exceptions: Add context when ignoring violations
Share standards: Use organization-level rules for consistency

API Design

Fix errors first: Address all error-level violations
Consider warnings: Review warnings and fix when reasonable
Learn from violations: Click rule links to understand best practices
Iterate: Improve your API design incrementally

Next Steps

Explore Rules: Browse the complete rule documentation to understand each best practice
Set Up CI/CD: Follow the API Integration Guide to automate validation
Customize Configuration: Adjust rules and severity levels for your project
Invite Your Team: Add team members to collaborate on API design

Troubleshooting

Upload Failed

Problem: Specification upload fails with an error

Common Solutions:

Check file is valid JSON/YAML: yamllint openapi.yaml
Verify file size is under 50MB
Ensure file contains valid OpenAPI 3.x specification
Check you have write permissions for the project

No Violations Shown

Problem: Upload succeeds but no violations appear

Possible Causes:

Specification is actually compliant (great job!)
All rules are disabled for the project
Evaluation is still in progress (refresh the page)

Cannot Create Project

Problem: Unable to create a new project