Tanzania Universities API 🎓

A robust REST API providing comprehensive data on Tanzanian higher education institutions with full CRUD operations and JWT authentication.

Features ✨

Complete University Data - Names, locations, courses, accreditation
Advanced Filtering - Search by location, course, or name
Secure Authentication - JWT protected endpoints
High Performance - Redis caching enabled
Auto Documentation - Interactive Swagger UI
Validation - Request payload validation
Pagination - Efficient data retrieval

Installation 🛠️

Prerequisites

Node.js 18+
npm 9+
Redis

Quick Start

# Install package
npm install tanzania-universities-api

# Or with yarn
yarn add tanzania-universities-api

Manual Setup

git clone https://github.com/charlesluguda/tanzania-universities-api.git
cd tanzania-universities-api
npm install
cp .env.example .env
npm start

Configuration ⚙️

.env file configuration:

PORT=3000
SECRET_KEY=your_secure_jwt_secret
REDIS_URL=redis://localhost:6379 # Optional
CACHE_DURATION=120 # Cache duration in seconds

API Documentation 📚

Explore the interactive API documentation:

http://localhost:3000/api-docs

Swagger UI Preview

Usage Examples 💻

JavaScript Implementation

const universityAPI = require('tanzania-universities-api');
const app = universityAPI();

app.listen(3000, () => {
  console.log('API running on port 3000');
});

API Endpoints

Method	Endpoint	Description	Auth Required
GET	`/universities`	List all universities	No
GET	`/universities/:id`	Get single university	No
POST	`/universities`	Create new university	Yes (Admin)
GET	`/universities/by-location`	Filter by location	No
GET	`/universities/by-course`	Filter by course offering	No

cURL Examples

Get universities in Dar es Salaam:

curl "http://localhost:3000/api/v1/universities/by-location?location=Dar%20es%20Salaam"

Create new university (authenticated):

curl -X POST http://localhost:3000/api/v1/universities \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "University of Dodoma",
    "location": "Dodoma",
    "courses": ["Education", "ICT"],
    "established": 2007
  }'

Data Model 📊

{
  "id": "udsm001",
  "name": "University of Dar es Salaam",
  "location": "Dar es Salaam",
  "accreditation": "TCU",
  "established": 1961,
  "website": "https://www.udsm.ac.tz",
  "courses": [
    "Medicine",
    "Engineering",
    "Law"
  ],
  "facilities": ["Library", "Labs"],
  "studentPopulation": 35000
}

Development 🧑‍💻

Running Tests

npm test

Linting

npm run lint

Contributing

Fork the repository
Create feature branch (git checkout -b feature/your-feature)
Commit changes (git commit -am 'Add some feature')
Push to branch (git push origin feature/your-feature)
Create Pull Request

License 📜

This project is licensed under the MIT License - see the LICENSE file for details.

Developed with ❤️ for Tanzania's education sector

Key Features of This README:

Visual Appeal: Badges, emojis, and clean formatting
Comprehensive Sections: All essential documentation areas
Code Friendly: Properly formatted code blocks
Table Formatting: For endpoints and other structured data
Visual Hierarchy: Clear section organization
Callouts: Important information highlighted
Professional Footer: With license and attribution

Package detail

tanzania-universities-api

readme