README.md

Malawi Music API

This API is built off whatever information is available from the Malawi music website, via the collect, plus some few other interesting bits of data that will be built up. Also, the API will provide an end-point for bulk downloading a collection of songs since the website doesn't yet allow that.

The aim is to build the API in such a way that other webapps and services can be built off the information. For example, a notification service for new song releases can use the information provided by the API to notify fans of certain artists, genres etc..

API Resources

• Artists
• Albums
• Songs
• BundleRequest
• SongCollectionBundle

Artists

The only supported method is GET. The artist represented as a Java Class here:

class Artist {

    String id;

    String name;

    String realName;

    String biography;

    String city;

    String country;

    Image profilePic;

    Date registeredOn;

    String website;

    String artistUrl;

    List<String> genres;

    List<String> albums;
}

class ArtistCompact {
    String id;

    String name;

    String artistUrl;
}

Albums

class Album {

    ArtistCompact artist;

    String id;

    String title;

    int year;

    String country;

    List<String> genres;

    String albumType;

    String albumUrl;

    int noOfViews;

    List<SongCompact> songs;
    
    int noOfSongs;
}

class AlbumCompact {
    String id;

    String title;

    String albumUrl;
}

Songs

class Song {

    ArtistCompact artist;

    AlbumCompact album;

    String title;

    String lyrics;

    List<String> genres;

    List<ArtistCompact> contributingArtists;

    String lengthHuman;

    int lengthMillis;

    String sizeHuman;

    int sizeBytes;

    int noOfPlays;

    int noOfDownloads;

    String songUrl;

    String downloadUrl;

    Date addedOn;

}

class SongCompact {

    String id;

    String songUrl;

    String downloadUrl;

    String name;

    int noOfPlays;

    int noOfDownloads;

    int sizeBytes;
}

BundleRequest

A bundle provides a way to download multiple songs in one request as an archive.

class BundleRequest {

    @NotNull List<@NotEmpty String> songIds;

    ArchiveFormat archiveAs;

    Optional<Date> requestedOn;

    Optional<String> requestId;

    Optional<String> bundleName;
}

enum ArchiveFormat {
    RAR,
    ZIP,
    TAR_GZ
}

SongCollectionBundle

A SongCollectionBundle is created by the system when it receives a create bundle request.

class SongCollectionBundle {
    /* The value from the requestId field in the create bundle request */
    String id;

    Date requestedOn;

    String bundleName;

    List<SongCompact> songs;

    String[] playOrder;

    List<String> artists;

    List<String> albums;

    List<String> genres;

    /* Generated by the system after bundling up the songs */
    String downloadUrl;
}