Xygil Backend

As of 2/21/2022, main branch code auto-deploys to api.xygil.net. But only skysnolimit08 has the ability to run migrations on the database it communicates with.

Setup updated 3/7/2022

(Note: I removed the mysqlclient package from Pipfile because it did not seem necessary and was causing problems for setup on Macs. Please let me know if this causes any problems down the line.)

Prerequisites

Git
Python 3
Pip

You can check if you have these by typing

(Windows)

$ git --version
$ python --version
$ pip --version

(Mac)

$ git --version
$ python3 --version
$ pip3 --version

If you don't have Git, download it from git-scm.com/downloads/
If you don't have Python 3, you can download it from https://www.python.org/downloads/
- on Windows if you install this, you will want to check the box for "add Python to PATH", or else you will have to retroactively do it manually or do it by modifying the install.
Pip or Pip 3 will install automatically when you install Python 3, which is great (unless you somehow prevent it, which you shouldn't).

Installing Dependencies

In your terminal, change directories into the folder you want to keep the project in. Then:

Windows

$ git clone https://github.com/skysnolimit08/dialecttranslationtool-backend backend
$ cd backend
$ pip install pipenv
$ pipenv install

Mac

$ git clone https://github.com/skysnolimit08/dialecttranslationtool-backend backend
$ cd backend
$ pip3 install pipenv
$ pipenv install

(The pip command will work on Windows; the pip3 command will work on Mac)

From now on, if you install a new package for the project, please do so using the command 'pipenv install package-name' from that same backend folder so that the Pipfile keeps track of what package dependencies our project needs for future developers and hosting servers.

Configuring Environmental Variables

Rename ".env-example" to ".env". Paste the following code into it. Create your own randomized value for SECRET_KEY. You can use python secrets to help you do that. Setting debug to True in your local environment will be helpful for debugging your code. You probably do not need to use the DATABASE_URL environmental variable, since our settings.py file includes a default database URL, but you are welcome to if you want to host your database in a special place.

SECRET_KEY='SECRET_KEY'
DEBUG_VALUE='True'
# DATABASE_URL=mysql://xygil:<password>@localhost:3306/xygil

Now, restart your terminal.

Connecting MySQL with Django

Windows

$ cd backend
$ pipenv shell
(venv) $ python manage.py migrate

Mac

$ cd backend
$ pipenv shell
(venv) $ python3 manage.py migrate

Configuring an administrative "superuser" for MySQL

Windows

$ pipenv shell
(venv) $ python manage.py createsuperuser
Username: 
Email address: 
Password: 
Password (again):

Mac

$ pipenv shell
(venv) $ python3 manage.py createsuperuser
Username: 
Email address: 
Password: 
Password (again):

Running the Server

Windows

$ pipenv shell
(venv) $ python manage.py runserver # Defaults to http://localhost:8000

Mac

$ pipenv shell
(venv) $ python3 manage.py runserver # Defaults to http://localhost:8000

Now, navigate to http://localhost:8000 and you should see the server running!

Models

`Audio`

class Audio:
    class Meta:
        verbose_name = "audio file"
        verbose_name_plural = "audio files"

    url             = CharField(max_length=255)
    title           = CharField(default="Untitled", max_length=255)
    archived        = BooleanField(default=False)

    # Metadata
    createdAt       = DateTimeField()
    updatedAt       = DateTimeField()
    lastUpdatedBy   = ForeignKey(User, null=True, on_delete=SET_NULL)

`Translation`

class Translation:
    class Meta:
        verbose_name = "translation"
        verbose_name_plural = "translations"

    title           = CharField(max_length=255)
    audio           = ForeignKey(Audio, on_delete=CASCADE)
    published       = BooleanField(default=False)

    # Metadata
    author          = ForeignKey(User, null=True, on_delete=SET_NULL)
    createdAt       = DateTimeField()
    updatedAt       = DateTimeField()
    lastUpdatedBy   = ForeignKey(User, null=True, on_delete=SET_NULL)

`Story`

class Story:
    class Meta:
        verbose_name = "story"
        verbose_name_plural = "stories"

    translation     = ForeignKey(Translation, null=True, on_delete=SET_NULL)

Xygil API

Users

Create, read, update, and delete user.

Create User

Working 3/7/2022. Did not test authentication. Is not safe and code needs to be deprecated and replaced with Django Auth functions.

URL : /user/

Method : POST

Auth required : Yes

Data example

{
    "username": "user1",
    "name": "Xygil Net",
    "email": "example@xygil.net",
    "password": "xygil123",
    "description": "A dude"
}

Read User

Working 3/7/2022.

URL : /user/:id

Method : GET

Auth required : No

Content example

{
    "email": "example@xygil.net",
    "name": "Xygil Net",
    "description": "A dude"
}

Update User

Is probably not safe and code needs to be deprecated and replaced with Django Auth functions.

URL : /user/:id

Method : PATCH

Auth required : Yes

Data example

{
    "email": "example@xygil.net",
    "password": "xygilxygil123"
}

Delete User

May not be safe to the point that code needs to be deprecated and replaced with Django Auth functions.

URL : /user/:id

Method : DELETE

Auth required : Admin

Index User Audios

3/7/2022 Can't get this to work, and not sure where to find the code for it in the backend.

URL : /user/:id/audio

Method : GET

Auth required : No

Content example

{
    "num": 2,
    "audio": [
        {
            "url": "aws.amazon.com/cloudfront/136523",
            "title": "Audio1",
            "id": 1,
            "description": "War and Peace"
            "public": true
        },
        {
            "url": "aws.amazon.com/cloudfront/12395323",
            "title": "Audio2",
            "id": 2,
            "description": "Gettysberg Address"
            "public": false
        },
    ]
}

Audio

Create, read, update, and delete audio.

Create Audio

Working on 3/7/2022. Authentication not tested.

URL : /audio/

Method : POST

Auth required : Yes

Data example

{
    "url": "aws.amazon.com/cloudfront/123456789",
    "title": "Audio1",
    "description": "Thirty minutes of people coughing",
}

Read Audio

Returns the link, name, description of an audio if public. Working on 3/7/2022. Authentication not tested.
URL : /audio/:id

Method : GET

Auth required : No

Content example

{
    "url": "aws.amazon.com/cloudfront/123456789",
    "title": "Audio1",
    "description": "Thirty minutes of people coughing"
}

Update Audio

As of 3/7/2022, it works.

URL : /audio/:id/

Method : PATCH

Auth required : Yes

Data example

{
    "description": "Twenty-seven minutes of people coughing",
}

Delete Audio

Working on 3/7/2022. Authentication not tested.

URL : /audio/:id

Method : DELETE

Auth required : Yes

Index Audios

Returns a list of all public audios. 3/7/2022 doesn't seem to work, probably because there is no "public" field in audio table.
URL : /user/:id/audio

Method : GET

Auth required : No

Content example

{
    "audio": [
        {
            "url": "aws.amazon.com/cloudfront/2151232",
            "title": "Audio1",
            "id": 1,
            "description": "War and Peace"
        }
    ]
}

Translations

Create, read, update, and delete translations associated with an audio.

Create Translation

Creates translation object. Returns the translation with language :lid of an audio :id. 3/7/2022 For this to work, need to comment out the Check unique section of views.py. But then that breaks some other things down the line.
URL : /audio/:id/translations/:lid

Method : POST

Auth required : Yes

Data example

{
    "user": "user1", 
    "title": "test title",
    "text": "Four score and seven years ago, our fathers brought forth on this continent...",
    "lid": 5,
    "public": false
}

Read Translation

Returns entire translation if public or authenticated and private. Working as of 3/7/2022. Did not test authentication.
URL : /audio/:id/translations/:lid

Method : GET

Auth required : Yes/No

Content example

{
    "text": "Four score and seven years ago, our fathers brought forth on this continent...",
}

Update Translation

Updates the entire text. This operation will automatically maintain existing associations for words that aren't deleted and insert NULL associations for newly inserted words. Working as of 3/7/2022. Did not test authentication.
URL : /audio/:id/translations/:lid/

Method : PATCH

Auth required : Yes

Data example

{
    "text": "Eighty-seven years ago, our fathers brought forth on this continent..."
}

Delete Translation

Works 3/7/2022. But doesn't delete or archive the associated stories.

URL : /audio/:id/translations/:lid

Method : DELETE

Auth required : Yes

Index Translation Languages

Returns a list of all available public languages for the translation.
URL : /audio/:id/translations

Method : GET

Auth required : No

Content example

{
    "languages": [0, 1, 3, 5, 6]
}

Languages

LanguageID to Language

URL : /languages

Method : GET

Auth required : No

Content example

{
    0: "English",
    1: "Spanish",
    2: "Chinese"
}

Associations

Get Associations for Highlighting

Returns the text between ts1 and ts2 along with a dictionary which maps sorted timestamp intervals to highlighted portions of text. Ex. From 0 to 3000 ms, characters between character index 0-9 and 16-20 (inclusive) should be highlighted (Four score/seven). From 3500 to 5000 ms, character from index 11-15 should be highlighted (and). If there are no configured associations, returns the entire text.
URL : /audio/:id/translations/:lid/associations?ts1=int&ts2=int

Method : GET

Auth required : No

Content example

{
    "text": "Four score and seven years ago, our fathers brought forth on this continent...",
    "associations": {
        "0-3000": ["0-9", "15-19"],
        "3500-5000": ["11-13"]        
    }
}

Update Associations

Given a portion of the text, associates particular indexes with timestamps(ms). The specific way how this works is the first portion of exclusive text matching this substring will be updated which is not ideal (since there may be infrequent cases of unintended associations if the "text" is too short) but simplifies the work done front end and the amount of text metadata needed immensely.
URL : /audio/:id/translations/:lid/associations

Method : POST

Auth required : Yes

Content example

{
    "text": "seven years ago, our fathers brought forth on this continent",
    "associations": {
        15: 2400,
        23: 1500,
        34: 3567
    }
}

Interpretations

Create, retrieve, update, and delete interpretations associated with an audio.

Create

Creates interpretation object. Have not completed after HTTP request endpoints as of 4/27/22.

URL : /storybooks/interpretations/audio/<int:audio_id>/

Method : POST

Auth required : Yes

Data example

{
    "id": "5", 
    "public": true,
    "shared_editors": [1, 2, 3],
    "shared_viewers": [1, 2, 3],
    "audio_ID": "5",
    "title": "test title",
    "latest_text": "Four score and seven years ago, our fathers brought forth on this continent...",
    "archived": false,
    "language_name": "English",
    "spaced_by": "_",
    "created_by": "me",
    "created_at": 04252022,
    "last_edited_by": "him",
    "last_edited_at": 04272022,
    "version": 1
}

Retrieve Audios

For a given audio file, a user can get a list of interpretations that they created, or which are shared with them for viewing and not archived, or which are shared with them for editing and not archived, or which are public and not archived. As of 4/27/2022, returns the entire interpretation, but should only return ID, title, created_by, language_name. Have not completed after HTTP request endpoints as of 4/27/22.

URL : /storybooks/interpretations/audio/<int:audio_id>/

Method : GET

Auth required : Yes

Content example

{
    "id": "5", 
    "title": "test title",
    "language_name": "English",
    "created_by": "me"
}

Retrieve Editors

A user can view an interpretation that is shared with them for editing and not archived. As of 4/27/2022, returns the entire interpretation, but should only return ID, public, title, latest_text, created_by, language_name, audio_id, last_edited_at.

URL : /storybooks/interpretations/<int:interpretation_id>/audio/<int:audio_id>/editor

Method : GET

Auth required : Yes

Content example

{
    "id": "5", 
    "public": true,
    "audio_ID": "5",
    "title": "test title",
    "latest_text": "Four score and seven years ago, our fathers brought forth on this continent...",
    "language_name": "English",
    "created_by": "me",
    "last_edited_at": 04272022,
}

Update Editors

If interpretation is not archived and shared_editors includes the current user, they can edit some fields of the interpretation. Title, public, language_name, and latest_text should be populated by logged-in user. Last_updated_by and last_updated_at should be autopopulated with logged-in user's uid and the timestamp of the fetch. Version should increment by 1. Have not completed after HTTP request endpoints as of 4/27/22.

URL : /storybooks/interpretations/<int:interpretation_id>/audio/<int:audio_id>/editor

Method : PATCH

Auth required : Yes

Retrieve Owners

A user can view an interpretation that they created. Returns all attributes of the interpretation.

URL : /storybooks/interpretations/<int:interpretation_id>/audio/<int:audio_id>/owner

Method : GET

Auth required : Yes

Content example

{
    "id": "5", 
    "public": true,
    "shared_editors": [1, 2, 3],
    "shared_viewers": [1, 2, 3],
    "audio_ID": "5",
    "title": "test title",
    "latest_text": "Four score and seven years ago, our fathers brought forth on this continent...",
    "archived": false,
    "language_name": "English",
    "spaced_by": "_",
    "created_by": "me",
    "created_at": 04252022,
    "last_edited_by": "him",
    "last_edited_at": 04272022,
    "version": 1
}

Update Owners

A logged-in user can edit all of the information about an interpretation that they created. Public, shared_editors, shared_viewers, audio_id, title, latest_text, archived, language_name, and spaced_by can be populated by the logged-in user. Last_updated_by and last_updated_at should be autopopulated with logged-in user's uid and the timestamp of the fetch. Version should increment by 1. Have not completed after HTTP request endpoints as of 4/27/22.

URL : /storybooks/interpretations/<int:interpretation_id>/audio/<int:audio_id>/owner

Method : PATCH

Auth required : Yes

Destroy

A logged-in user can delete all of the information about an interpretation that they created. Have not completed after HTTP request endpoints as of 4/27/22.

URL : /storybooks/interpretations/<int:interpretation_id>/audio/<int:audio_id>/owner

Method : DELETE

Auth required : Yes

Retrieve All

A user can get a list of interpretations that they created, or which are shared_with them for viewing and not archived, or which are shared_with them for editing and not archived. As of 4/27/2022, returns the entire interpretation, but should only return ID, public, title, archived, spaced_by, created_by, language_name, audio_id, last_edited_at.

URL : /storybooks/interpretations/

Method : GET

Auth required : Yes

Content example

{
    "id": "5", 
    "public": true,
    "audio_ID": "5",
    "title": "test title",
    "archived": false,
    "language_name": "English",
    "spaced_by": "_",
    "created_by": "me",
    "created_at": 04252022,
    "last_edited_at": 04272022,
}

Retrieve User

Anybody can get a list of interpretations created by a user and public and not archived. As of 4/27/2022, returns the entire interpretation, but should only return ID, title, created_by, language_name, audio_id.

URL : /storybooks/interpretations/

Method : GET

Auth required : No

Content example

{
    "id": "5", 
    "audio_ID": "5",
    "title": "test title",
    "language_name": "English",
    "created_by": "me",
}

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
backend		backend
storybooks		storybooks
.DS_Store		.DS_Store
LICENSE		LICENSE
Pipfile		Pipfile
Pipfile.lock		Pipfile.lock
Procfile		Procfile
README.md		README.md
db.sqlite3		db.sqlite3
manage.py		manage.py
show		show

License

rohanbhatia7/Yakalo-Collective

Folders and files

Latest commit

History

Repository files navigation

Xygil Backend

Setup updated 3/7/2022

Prerequisites

Running the Server

Models

Audio

Translation

Story

Xygil API

Users

Create User

Read User

Update User

Delete User

Index User Audios

Audio

Create Audio

Read Audio

Update Audio

Delete Audio

Index Audios

Translations

Create Translation

Read Translation

Update Translation

Delete Translation

Index Translation Languages

Languages

LanguageID to Language

Associations

Get Associations for Highlighting

Update Associations

Interpretations

Create

Retrieve Audios

Retrieve Editors

Update Editors

Retrieve Owners

Update Owners

Destroy

Retrieve All

Retrieve User

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

`Audio`

`Translation`

`Story`

Packages