EWP in GitHub

Owned by Stavros Ladas
Last updated: 4 Nov 24 by Janina Mincer-Daszkiewicz
5 min read

EWP in GitHub

GitHub is a platform and cloud-based service for software development and version control using Git, allowing developers to store and manage their code and documentation. It provides the distributed version control of Git plus access control, bug tracking, software feature requests, task management, continuous integration, and wikis. It is commonly used to host open source software development projects.

Technical documentation of the EWP Network and the public code are stored in GitHub. There is an “organization” named Erasmus Without Paper which owns a set of repositories in Github located at https://github.com/erasmus-without-paper.

Documentation and source code are publicly available and open-sourced. This means that anyone can read, comment on and contribute to its development. Rules for accepting change proposals are also explained in GitHub.

All specifications and code in GitHub are licensed under MIT License, see e.g. https://github.com/erasmus-without-paper/ewp-specs-architecture/blob/stable-v1/LICENSE.

This document contains the general information about GitHub repositories of the EWP Network, information about repositories with the description of the network architecture and security protocols, repositories related to the EWP Registry, and repositories which contain a source code.

All active GitHub repositories related to EWP are documented on a separate page:

Documents and specifications

GitHub repositories

In November 2023 there are 76 repositories in GitHub, 18 of which were archived.

There are 26 public repositories for APIs – their names start with the prefix ewp-specs-api. Typically they follow the same structure and contain (among others) the following elements:

Repositories with APIs are listed in a separate section, with a short description of their content.

Some supplementary repositories are listed and explained below.

Introduction to EWP Network

Architecture and common datatypes

Description of EWP’s Architecture and Security

This document describes EWP vocabulary, network components, common features and data types, and explains basic rules about how partners communicate with each other and handle errors.

Authentication and security

Authentication and security in the context of the EWP Network is described in this GitHub repository. The security of the communication is split into four security aspects, for which the following methods are available:

Each endpoint of each API must support at least one method of covering each of these security aspects. Before making the request, clients verify security protocols supported by the server, and construct their request appropriately.

Registry

The following repositories in GitHub are related to the EWP registry:

  1. EWP Registry API. It contains a specification of the EWP Registry API. The Registry API is implemented by the Registry Service.

  2. EWP Registry Service. It contains the Java implementation of the registry server part. There are two public installations of the EWP registry:

    1. PROD Network,

    2. DEV Network.

  3. EWP Registry Client. It contains Java implementation of the EWP Registry Service client.

    1. Developers, who implement a client, can use it to discover institutions in the network and APIs implemented by them.

    2. Developers, who implement a server, can use it to verify incoming requests (prove that they come from within the EWP network and prove which institutions the requester covers).

  4. EWP Registry Catalogue. It contains the implementation of the application that enables replicating the EWP registry service on multiple servers.

  5. EWP Registry log. It contains a record of changes made to the Registry’s catalogue in the production network (for logging purposes).

  6. EWP DEV Registry log. It contains a record of changes made to the DEV Registry’s catalogue (for logging purposes).

The Registry Service is described in GitHub. It allows all EWP hosts to access the list of other EWP hosts and to list APIs implemented by these hosts, along with the URLs these APIs are implemented at.

The registry is being updated automatically. It periodically reads all the information that all EWP Hosts provide within their Discovery Manifest files, and these changes are instantly reflected in the Registry Service responses.

The major advantage of such automatic updating is that the partners do not need to contact the registry maintainer when they want to change some of their Registry entries. Most changes in the registry can be performed simply by updating the manifest on the partner's server (and the Registry will fetch these changes automatically). This process is both more convenient and more secure than updating the registry manually.

Catalogue file

The Registry Service catalogue file endpoint takes no parameters and returns the response at a specified URL. The response format is described in the catalogue.xsd file.

Security is based on server certificate validation. The registry does not validate the client (all clients are allowed to access the catalogue anonymously).

EWP Registry Catalogue which enables replicating the EWP registry service on multiple servers pulls the most recent version of the catalogue file from ewp-registry-log-prod and ewp-registry-log-dev, respectively.

Github source code

Some EWP-related GitHub repositories contain the source code and binaries.

  1. EWP Registry Service contains Java implementation of the registry server part. It is distributed as a Docker image.

  2. EWP Registry Client contains Java implementation of the EWP Registry Service client library:

    1. Developers, who implement a client, can use it to discover institutions in the network and APIs implemented by them.

    2. Developers, who implement a server, can use it to verify incoming requests (prove that they come from within the EWP network and prove which institutions the requester covers).

  3. IIAs API repository contains

    1. a folder xslKit with XSLT templates and Java class example;

    2. a code in Go language for hash calculation.

There are two Maven libraries: EWP registry client and Java support library for aes128gcm encryption format, which can be included in the external code. Because GitHub cannot be used for sharing Maven libraries, they are distributed from the sonatype.org public repository.

The EWP registry can be installed in a local environment for testing local development installation. There is a package ready for download with embedded README and HOWTO files. The local environment package is named local_configuration.zip.

Issues

Each EWP repository has its own, separate issue tracker. If a developer plans to submit a new issue, and the topic of this issue applies to the contents of a single repository only, then it should be submitted in the issue tracker of this repository. There is also one special repository, general-issues, for tracking issues which do not apply to any single project.

Issues contain suggestions, ideas, which may be inspiring, some are used actively by developers discussing details of their implementations, and others contain change proposals. Some issues are kept open for a long time as discussions are ongoing.

Open issues in GitHub (if you get a 404 error, then sign in to GitHub first)