mirror of
https://github.com/System-End/hackatime.git
synced 2026-04-19 22:15:14 +00:00
refactor: fix insite api docs to use swagger (#879)
This commit is contained in:
Echo
GitHub
parent
f16141bf62
commit
5d94361f5a
5 changed files with 6 additions and 350 deletions
|
|
@ -7,6 +7,11 @@ class DocsController < ApplicationController
|
|||
|
||||
def show
|
||||
@doc_path = sanitize_path(params[:path] || "index")
|
||||
|
||||
if @doc_path.start_with?("api")
|
||||
redirect_to "/api-docs", allow_other_host: false and return
|
||||
end
|
||||
|
||||
@breadcrumbs = build_breadcrumbs(@doc_path)
|
||||
|
||||
file_path = safe_docs_path("#{@doc_path}.md")
|
||||
|
|
|
|||
|
|
@ -67,9 +67,7 @@
|
|||
<div class="bg-dark rounded-lg p-6">
|
||||
<h4 class="text-xl font-semibold text-primary mb-4">For Coders</h4>
|
||||
<ul class="space-y-3">
|
||||
<li><%= link_to "API Overview", doc_path("api/overview"), class: "text-white hover:text-primary" %> <span class="text-secondary">- How to use our code API</span></li>
|
||||
<li><%= link_to "Authentication", doc_path("api/authentication"), class: "text-white hover:text-primary" %> <span class="text-secondary">- How to log in with code</span></li>
|
||||
<li><%= link_to "Endpoints", doc_path("api/endpoints"), class: "text-white hover:text-primary" %> <span class="text-secondary">- All the API commands</span></li>
|
||||
<li><a href="/api-docs" class="text-white hover:text-primary">API Documentation</a> <span class="text-secondary">- Interactive API docs with Swagger</span></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -1,95 +0,0 @@
|
|||
# How to Log In With Code
|
||||
|
||||
Here's how to use your API key to access Hackatime data with code.
|
||||
|
||||
## Get Your API Key
|
||||
|
||||
Every API request needs your personal API key.
|
||||
|
||||
### Finding Your API Key
|
||||
|
||||
1. Log in to [Hackatime](https://hackatime.hackclub.com)
|
||||
2. Go to [Settings](https://hackatime.hackclub.com/my/settings)
|
||||
3. Copy your API key from the page
|
||||
|
||||
### Using Your API Key
|
||||
|
||||
Put your API key in the Authorization header:
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer YOUR_API_KEY" \
|
||||
https://hackatime.hackclub.com/api/v1/stats
|
||||
```
|
||||
|
||||
## Other Ways to Send Your Key
|
||||
|
||||
### In the URL
|
||||
|
||||
You can also put your API key in the URL:
|
||||
|
||||
```bash
|
||||
curl "https://hackatime.hackclub.com/api/v1/stats?api_key=YOUR_API_KEY"
|
||||
```
|
||||
|
||||
**Note**: The Authorization header way is safer.
|
||||
|
||||
## Test Your Key
|
||||
|
||||
Try your API key with this simple request:
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer YOUR_API_KEY" \
|
||||
https://hackatime.hackclub.com/api/v1/stats
|
||||
```
|
||||
|
||||
If it works, you'll get something like:
|
||||
|
||||
```json
|
||||
{
|
||||
"total_seconds": 12345,
|
||||
"languages": [...],
|
||||
"projects": [...]
|
||||
}
|
||||
```
|
||||
|
||||
## What Happens When Something Goes Wrong
|
||||
|
||||
### Wrong API Key
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Invalid API key"
|
||||
}
|
||||
```
|
||||
|
||||
### No API Key
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "API key required"
|
||||
}
|
||||
```
|
||||
|
||||
## Rate Limits
|
||||
|
||||
We don't enforce hard limits right now, but be reasonable:
|
||||
|
||||
- Don't make thousands of requests per minute
|
||||
- The WakaTime plugin automatically limits heartbeats to every 30 seconds
|
||||
|
||||
## Keep Your Key Safe
|
||||
|
||||
- **Never put API keys in your code** that others can see
|
||||
- **Use environment variables** to store your API key
|
||||
- **Only use HTTPS** (never HTTP) for API requests
|
||||
- **Get a new key** if you think yours was stolen
|
||||
|
||||
## Need Help?
|
||||
|
||||
Having trouble with your API key? Check:
|
||||
|
||||
1. You copied the whole key correctly
|
||||
2. You're using the right website URL
|
||||
3. Your request looks like the examples above
|
||||
|
||||
Still stuck? Ask for help in [Hack Club Slack](https://hackclub.slack.com) (#hackatime-v2 channel)!
|
||||
|
|
@ -1,201 +0,0 @@
|
|||
# All the API Commands
|
||||
|
||||
Here are all the ways you can get data from Hackatime with code.
|
||||
|
||||
## How to Log In
|
||||
|
||||
All requests need your API key:
|
||||
|
||||
- **Best way**: `Authorization: Bearer YOUR_API_KEY` in the header
|
||||
- **Other way**: Add `?api_key=YOUR_API_KEY` to the URL
|
||||
|
||||
Get your API key from [Hackatime settings](https://hackatime.hackclub.com/my/settings).
|
||||
|
||||
## For WakaTime Tools
|
||||
|
||||
These work with existing WakaTime apps and libraries.
|
||||
|
||||
### Get Today's Time
|
||||
|
||||
```bash
|
||||
GET /api/hackatime/v1/users/{user_id}/statusbar/today
|
||||
```
|
||||
|
||||
Shows how much you've coded today.
|
||||
|
||||
**What you get back**:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"grand_total": {
|
||||
"total_seconds": 7200.0,
|
||||
"text": "2 hrs"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Hackatime-Only Commands
|
||||
|
||||
These are special to Hackatime.
|
||||
|
||||
### Leaderboards (Admin Only)
|
||||
|
||||
Daily and weekly leaderboards of total coding time.
|
||||
|
||||
```bash
|
||||
GET /api/v1/leaderboard # alias for daily
|
||||
GET /api/v1/leaderboard/daily
|
||||
GET /api/v1/leaderboard/weekly
|
||||
```
|
||||
|
||||
Authentication:
|
||||
|
||||
- Requires the Stats API key: use `Authorization: Bearer STATS_API_KEY` or `?api_key=STATS_API_KEY`
|
||||
- In development, these endpoints may work without a key
|
||||
|
||||
Response (example):
|
||||
|
||||
```json
|
||||
{
|
||||
"period": "daily",
|
||||
"start_date": "2025-12-20T00:00:00Z",
|
||||
"date_range": "Sat, Dec 20, 2025",
|
||||
"generated_at": "2025-12-20T00:05:12Z",
|
||||
"entries": [
|
||||
{
|
||||
"rank": 1,
|
||||
"user": {
|
||||
"id": 123,
|
||||
"username": "alice",
|
||||
"avatar_url": "https://.../avatar.png"
|
||||
},
|
||||
"total_seconds": 14400
|
||||
},
|
||||
{
|
||||
"rank": 2,
|
||||
"user": {
|
||||
"id": 456,
|
||||
"username": "bob",
|
||||
"avatar_url": "https://.../avatar.png"
|
||||
},
|
||||
"total_seconds": 10800
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `weekly` uses a 7-day window and returns `period: "last_7_days"` with a multi-day `date_range`
|
||||
- If the leaderboard is still generating, returns `503` with `{ "error": "Leaderboard is being generated" }`
|
||||
- If the API key is invalid or missing, returns `401` with `{ "error": "Unauthorized" }`
|
||||
|
||||
### Your Coding Stats
|
||||
|
||||
```bash
|
||||
GET /api/v1/stats
|
||||
```
|
||||
|
||||
Get how much you've coded overall.
|
||||
|
||||
### Someone Else's Stats
|
||||
|
||||
```bash
|
||||
GET /api/v1/users/{username}/stats
|
||||
```
|
||||
|
||||
See someone else's public coding stats.
|
||||
|
||||
**What you get back**:
|
||||
|
||||
```json
|
||||
{
|
||||
"user": "username",
|
||||
"total_seconds": 86400,
|
||||
"languages": [
|
||||
{ "name": "Python", "seconds": 43200 },
|
||||
{ "name": "JavaScript", "seconds": 28800 }
|
||||
],
|
||||
"projects": [{ "name": "my-app", "seconds": 36000 }]
|
||||
}
|
||||
```
|
||||
|
||||
### Your Raw Activity Data
|
||||
|
||||
```bash
|
||||
GET /api/v1/my/heartbeats
|
||||
GET /api/v1/my/heartbeats/most_recent
|
||||
```
|
||||
|
||||
Get the raw data about when you coded.
|
||||
|
||||
**Options you can add**:
|
||||
|
||||
- `start` - Start date
|
||||
- `end` - End date
|
||||
- `limit` - How many results (max 100)
|
||||
|
||||
### Find Users
|
||||
|
||||
```bash
|
||||
GET /api/v1/users/lookup_email/{email}
|
||||
GET /api/v1/users/lookup_slack_uid/{slack_uid}
|
||||
```
|
||||
|
||||
Find users by their email or Slack ID.
|
||||
|
||||
### User Trust Factor
|
||||
|
||||
```bash
|
||||
GET /api/v1/users/{username}/trust_factor
|
||||
```
|
||||
|
||||
Get a user's trust factor.
|
||||
|
||||
**What you get back**:
|
||||
|
||||
```json
|
||||
{
|
||||
"trust_level": "yellow",
|
||||
"trust_value": 0
|
||||
}
|
||||
```
|
||||
|
||||
## Try These Examples
|
||||
|
||||
### See Your Recent Activity
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer YOUR_API_KEY" \
|
||||
"https://hackatime.hackclub.com/api/v1/my/heartbeats?limit=10"
|
||||
```
|
||||
|
||||
### See Today's Time
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer YOUR_API_KEY" \
|
||||
"https://hackatime.hackclub.com/api/hackatime/v1/users/current/statusbar/today"
|
||||
```
|
||||
|
||||
## Limits
|
||||
|
||||
- **Heartbeats**: WakaTime plugins wait 30 seconds between sends
|
||||
- **API Requests**: No hard limits, but don't go crazy
|
||||
|
||||
## When Things Go Wrong
|
||||
|
||||
Errors look like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Invalid API key"
|
||||
}
|
||||
```
|
||||
|
||||
Common problems:
|
||||
|
||||
- `401` - Bad or missing API key
|
||||
- `404` - That thing doesn't exist
|
||||
- `500` - Something broke on our end
|
||||
|
|
@ -1,51 +0,0 @@
|
|||
# How to Use Our Code API
|
||||
|
||||
The Hackatime API lets you get your coding data with code. It works just like WakaTime's API.
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Get your API key from [Hackatime settings](https://hackatime.hackclub.com/my/settings)
|
||||
2. Make requests to: `https://hackatime.hackclub.com/api/v1/`
|
||||
|
||||
## How to Log In With Code
|
||||
|
||||
Put your API key in your requests like this:
|
||||
|
||||
**Best way (Authorization Header)**:
|
||||
|
||||
```text
|
||||
Authorization: Bearer YOUR_API_KEY
|
||||
```
|
||||
|
||||
**Other way (in the URL)**:
|
||||
|
||||
```text
|
||||
?api_key=YOUR_API_KEY
|
||||
```
|
||||
|
||||
## Try It Out
|
||||
|
||||
Get your coding stats:
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer YOUR_API_KEY" \
|
||||
https://hackatime.hackclub.com/api/v1/users/{your-username}/stats
|
||||
```
|
||||
|
||||
## Works With WakaTime Tools
|
||||
|
||||
Since Hackatime works like WakaTime's API, you can:
|
||||
|
||||
- Use any WakaTime code libraries
|
||||
- Point WakaTime tools to Hackatime
|
||||
- Move data between WakaTime and Hackatime
|
||||
|
||||
## Popular Endpoints
|
||||
|
||||
- **Your Stats**: `/api/v1/stats` - How much you've coded (Admin Only)
|
||||
- **Your Heartbeats**: `/api/v1/my/heartbeats` - Raw coding activity
|
||||
- **User Stats**: `/api/v1/users/{username}/stats` - Any user's public stats
|
||||
|
||||
## More Details
|
||||
|
||||
Want to see all the API commands? Check out our [complete API list](./endpoints.md). Most things work exactly like [WakaTime's API](https://wakatime.com/developers).
|
||||
Loading…
Add table
Reference in a new issue