episciences-api

About Episciences REST API

The Episciences REST API can be used with authentication and authorisation.

Authentication is reserved exclusively for users of one of the Episciences journals, so, it is vital to recover your API password - once you have logged on to the journal site - via My space > Reset my API password.

Get the authentication token with a POST request

The API is called up securely via a JWT token, which can be retrieved via "/api/login" endpoint:

NOTE: About "code": you have to use only the journal's code (e.g. "code": "epijinfo").

curl -X 'POST' \
'https://api-preprod.episciences.org/api/login' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"username": "login",
"password": "api pwd",
"code": "journal’s code (e.g. epijinfo)"
}'

Response type:

{"token":"eyJ0eXAiOiJKV1….", refresh_token":"3ff818151dd…"}

The token expires after one hour. The refresh_token expires after one month.

It is possible to generate a new token without asking the user to enter these identifiers via "api/token/refresh":

curl -X 'POST' \
'https://api-preprod.episciences.org/api/token/refresh' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"refresh_token": "3ff818151dd…"
}'

To check that you're connected and as an example of how to use it:

curl -X 'GET' \
'https://api-preprod.episciences.org/api/me' \
-H 'accept: application/ld+json' \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1….'

To explore the available endpoints: https://api-preprod.episciences.org/api

Testing the API Manually

1. Expand /api/login, click the Try it out button and enter your account information.
2. Next, press the execute button, it will respond with a failed or passed result.
3. In this case, we get the passed result response, with response code 200.
4. Take the token string and put it in Authorize.
5. After the authorization step, we are now ready to test the API

Development Setup

This section covers setting up the Episciences API for local development using Docker.

Prerequisites

Before starting, ensure you have the following installed:

• Docker and Docker Compose - Install Docker
• Git - For cloning the repository
• OpenSSL - For SSL certificate generation (automatically checked by Makefile)

Quick Start

1. Clone the repository:

   git clone <repository-url>
   cd episciences-api

2. Start the development environment:

   make docker-up

   This command will:

   • Automatically generate SSL certificates for HTTPS development
   • Start all required containers (PHP-FPM, Apache, MySQL)
   • Set up the complete development environment

3. Add the local domain to your hosts file:

   echo "127.0.0.1 api-dev.episciences.org" | sudo tee -a /etc/hosts

4. Access the application:

   • API Documentation: https://api-dev.episciences.org:8443/api/docs
   • Interactive API Explorer: https://api-dev.episciences.org:8443/api
   • Main Application: https://api-dev.episciences.org:8443/

Development Environment

Available Make Commands

Run make help to see all available commands. Key commands for development:

# Environment Management
make docker-up         # Start all containers (auto-generates SSL certificates)
make docker-down       # Stop all containers
make docker-restart    # Restart all containers
make docker-status     # Check container status
make docker-logs       # Follow container logs

# Development Tools
make docker-shell      # Enter PHP container for debugging
make docker-mysql      # Access MySQL database
make docker-test       # Run PHPUnit tests in container

# SSL Certificate Management
make ssl-certs         # Generate SSL certificates manually
make ssl-clean         # Remove SSL certificates

HTTPS Development Setup

The development environment uses HTTPS with a local domain for production-like conditions:

• Domain: api-dev.episciences.org
• HTTPS Port: 8443
• HTTP Port: 8080 (redirects to HTTPS)

Important: You'll see a browser security warning because we use self-signed certificates for development. This is normal - click "Advanced" → "Proceed to api-dev.episciences.org" to continue.

SSL Certificate Management

SSL certificates are automatically generated when you run make docker-up. Key points:

• Certificates are not committed to the repository for security
• Each developer generates their own certificates locally
• Certificates are valid for 1 year and include proper server authentication extensions
• Use make ssl-clean ssl-certs to regenerate certificates if needed

Testing & Development Workflow

Running Tests

# Run tests in Docker container (recommended)
make docker-test

# Run tests locally (requires local PHP 8.2+ setup)
make test
make test-unit          # Unit tests only
make test-coverage      # Tests with coverage report

Database Access

# Access MySQL via container
make docker-mysql

# Or connect with external tools using:
# Host: localhost
# Port: 3306
# User: root
# Password: root
# Database: episciences

Development URLs

• API Documentation: https://api-dev.episciences.org:8443/api/docs
• OpenAPI Spec: https://api-dev.episciences.org:8443/api/docs.json
• Symfony Profiler: https://api-dev.episciences.org:8443/_profiler

Troubleshooting

Common Issues:

1. "Connection refused" error: Check if containers are running with make docker-status

2. "SSL certificate error": This is expected for self-signed certificates - proceed past the browser warning

3. "Port already in use": Stop existing containers with make docker-down or check for conflicting services on ports 8080, 8443, 3306

4. Permission issues: Ensure Docker has proper permissions and your user is in the docker group

5. SSL certificate issues: Regenerate certificates with make ssl-clean ssl-certs

Getting Help:

• Run make help to see all available commands
• Check container logs with make docker-logs
• Verify setup with make check-prereqs