CoDeKu DevOps Academy Blog - DevOps & Cloud Blogging Platform
Hands-On Guide · Part 2
Build, Secure, Succeed.
Let’s get hands-on. A streamlined, step-by-step guide from spinning up your first API to making a real authenticated request.
⚡
📖
Quick recap from Part 1
Gravitee acts as a smart API gateway between your clients and your backend, enforcing auth and policies in real time. To move forward, remember the Core Trio: The API (the service you expose), The Plan (the access rulebook and security contract), and The Application (the registered consumer entity). With these defined, we are ready to build.
Overview
The 9-Step Journey
Follow the path from right to left, then down to completion.
🏗️
Step 01
Create API
←
🎯
Step 02
Backend
←
🚪
Step 03
Entrypoints
←
🛠️
Step 04
Policies
←
📜
Step 05
Plan
↓
🚀
Step 06
Deploy
→
📢
Step 07
Publish
→
🤝
Step 08
Subscribe
→
Success
✨
Step 09
Live Request
Step 1
Choose API Version
Head to the Gravitee Management Console and click APIs → Add API. You’ll be prompted to select a creation method.
🆕
Select v4 API
Always choose the v4 API creation method it’s the recommended path and ensures forward compatibility with all upcoming Gravitee features.
🏷️
Name Your API
Enter a clear, descriptive name e.g., User Service API. This appears in the Developer Portal, so make it readable for other developers on your team.
Step 2
Configure Proxy Settings
Tell Gravitee what kind of backend you’re wrapping and how to communicate with it.
🔌
Choose Proxy Type
Select HTTP Proxy for REST APIs, Message for event-based backends (Kafka, MQTT), or GraphQL for GraphQL services.
🔒
Configure Encryption
Gravitee handles SSL/TLS termination at the Gateway level. Note: If your backend requires mTLS, ensure you configure the client certificates at the Endpoint level.
Step 3
Define Context Path & Backend
This step wires your public-facing URL to the actual backend service running internally.
🛣️
Context Path
The public URL fragment clients will call e.g., /api/users. The Gateway intercepts all traffic matching this path.
🎯
Backend / Target URL
Your actual internal service endpoint e.g., http://user-service:8080/v1. Validated requests are proxied here by Gravitee.
Step 4
Create Security Plans
Plans define how consumers authenticate and how much traffic they’re permitted. Every API needs at least one.
🗝️
API Key
A simple token passed in a header. Fast to set up. Good for identification not strong authorization. Best for internal or dev APIs.
🔐
OAuth2
Recommended
Industry standard. Grants tokens via
client_id + client_secret. The right choice for any production-facing API.🎟️
JWT
Recommended
Stateless token-based auth with claims validation. Ideal when you already have an identity provider in your stack.
📣
Push
For push-based messaging patterns lets the server initiate communication to subscribed clients. Designed for message-based APIs.
🔓
Keyless
Open access with no authentication required. Suitable for public documentation or internal dev environments use very cautiously in production.
Inside every plan you can also configure rate limits (requests per second) and quotas (requests per day or month) to protect your backend from overload.
Step 5
Apply Policies (Optional)
Policies are rules applied at the gateway level to every request or response before your backend ever sees the traffic.
⏱️
Rate Limiting & Quota Management
Cap requests per second or per billing period. Prevent abuse and ensure fair usage across all consumers.
🔄
Request / Response Transformation
Modify headers, rewrite bodies, inject or strip fields on the fly no backend code changes needed.
⚡
Caching
Cache responses at the gateway layer. Dramatically reduces backend load for read-heavy endpoints.
✅
Custom Validation Rules
Validate request structure, required fields, or payloads before they ever reach your backend service.
🌐
IP Filtering & CORS Configuration
Whitelist or blacklist IP ranges and configure cross-origin headers centrally — once, enforced for all consumers.
Once satisfied, review the full summary and click Save.
Step 6
Deploy & Publish
🚀
Deploy the API
Click Deploy in the console. This activates your API on the running Gateway instance — traffic can now flow through it.
📢
Publish Plans to the Developer Portal
Publishing makes your API discoverable. Developers can browse, read docs, and subscribe to plans entirely self-service no manual coordination required from your team.
Step 7
Manage Access & Groups
Control who on your team can view and manage this API through the Gravitee Management Console.
👥
Create Groups
Organise users by team or department. Groups let you grant access to many people at once instead of managing permissions individually.
🏅
Assign Roles & Permissions
Invite members and set granular roles control who can view, who can subscribe, and who can manage the API configuration.
Step 8
Application & Subscription Flow
This is how consumers receive credentials the full lifecycle from registration to a working key or token in hand.
📱
1 · Register an Application
In the Developer Portal, create an Application a named, tracked identity that represents the client system calling your API.
📋
2 · Subscribe to a Plan
Choose the plan matching your auth and rate limit needs. Submit the request the publisher can approve manually or enable auto-validation for instant access.
⏳
3 · Wait for Approval
The API publisher reviews the subscription request. With auto-validation enabled, credentials are issued immediately upon subscription submission.
🔑
4 · Receive Credentials
Once approved, you receive credentials tied to your subscription an API key, or a client_id / client_secret for OAuth2, or a JWT. Keep them safe.
Step 9
Test Your API
Fire your first real request through the Gateway to verify the Live Request flow.
curl -H “X-Gravitee-Api-Key: your-api-key” \
https://gateway.example.com/users
https://gateway.example.com/users
What the Gateway May Return
Status codes returned by the Gateway before reaching your backend:
200
Success: Request reached backend.
401
Auth Failed: Check your API key.
403
Forbidden: Access denied.
429
Limit: Too many requests.
502
Bad Gateway: Backend unreachable.
💡
Pro Tips
- → Security Best Practice: Use OAuth2 or JWT for production APIs. API keys are identifiers they don’t expire or carry claims and aren’t proper authorization tokens.
- → Automation: Gravitee has a powerful CLI. Script your entire API deployment, plan creation, and configuration as part of your CI/CD pipeline no manual clicking required.
- → Developer Portal: Enable auto-validation for low-risk plans. It eliminates manual approval overhead and lets developers self-serve credentials instantly.
🎉
Ready to Go!
Your API is deployed, secured with a plan, and accessible with real credentials. Interested in exploring further? Access the official documentation or connect with the community.
Happy API Building! 🚀
Gravitee API Management Series · Part 1: Introduction · Part 2: Creating Your First API
