Api List Path

ExpressJS example server and client API

⬆️ Top of Document
🏗️ Requirements
⚡ Quick Start
🧰 Usage
🗒 Setup Notes
📈 Contributing
- 🔱 Forking
- 💱 Sponsor
📇 Attribution
⚖️ Licensing

Requirements

NodeJS and NPM are utilized by this project to track and install dependencies, check the official Downloading and installing Node.js and npm guide for details.

Quick Start

Clone Project

mkdir -vp ~/git/hub/web-dev-examples

cd ~/git/hub/web-dev-examples

git clone git@github.com:web-dev-examples/api-list-path.git

Install All Dependencies (option 1)

npm install

Install Development Dependencies (option 2)

npm install --only=dev

Install Production Dependencies (option 3)

npm install --production

Run ExpressJS Server

npm run start

Navigate to http://localhost:8080/ within a web-browser to interact with API via UI, or send Curl commands similar to...

curl --data 'path=.' --url 'http://localhost:8080/list'

Usage

After editing files under ts/ directory transpile JavaScript via...

npm run ts-build

Setup Notes

Steps preformed to construct this project

Initialize Version Management

git init api-list-path

cd api-list-path

Development Dependencies

npm install --save-dev @types/express\
                       @types/node\
                       nodemon\
                       typescript

App Dependencies

npm install --save body-parser express

Directory/File Structure

touch .gitignore


touch tsconfig.json
touch tsconfig.back-end.json
touch tsconfig.front-end.json


mkdir -p ts/back-end/routes/list
touch ts/back-end/index.ts
touch ts/back-end/routes/index.ts
touch ts/back-end/routes/list/post.ts


mkdir -p front-end/assets/js
touch front-end/index.html


mkdir -p ts/front-end/assets/js
touch ts/front-end/assets/js/index.ts

Overview

package.json NPM configurations

Check the "script" key for available npm run <target> options

.gitignore configures directory/file patterns that Git should ignore from version control by default.

Ignored directories and/or files can be added via -f or --force option, eg...

git add -f ignored-file.ext

tsconfig.json contains shared TypeScript transpiling configurations.
tsconfig.back-end.json back-end specific TypeScript transpiling configurations.
tsconfig.front-end.json front-end specific TypeScript transpiling configurations.
tsconfig.jest.json Jest test specific TypeScript transpiling configurations.

Multi-configuration setups with TypeScript can be a bit tricky; the main tsconfig.json should contain configurations shared by all projects, and any project specific files should then overwrite and/or add further customization.

tsconfig.back-end.json

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "back-end",
    "lib": [ "es2017" ],
    "esModuleInterop": true,
    "moduleResolution": "node",
    "module": "commonjs"
  },
  "include": [
    "ts/back-end/**/*.ts"
  ],
  "exclude": [
    "node_modules",
    "ts/front-end",
    "ts/jest"
  ]
}

The "outDir" key defines where transpiled JavaScript files will be saved

The "include" key defines a list of directory/file paths that will be transpiled by current configurations

The "exclude" key defines a list of directory/file paths that should not be transpiled by current configurations

package.json (snip)

{
  /* ... */
  "scripts": {
    "nodemon": "nodemon back-end/index.js",
    "start": "node back-end/index.js",
    "ts-build-back-end": "tsc --project tsconfig.back-end.json",
    "ts-watch-back-end": "tsc --project tsconfig.back-end.json ts/back-end --watch",
  },
  /* ... */
}

The --project parameter of tsc commands defines a configuration file to be used for transpiling

ts/back-end/ directory contains TypeScript source files for back-end server
ts/back-end/index.ts initializes ExpressJS server, with configurations, and imports route callbacks
ts/back-end/routes/index.ts imports, and names, route callback functions
ts/back-end/routes/list/post.ts defines callback function for <hostname>/list route HTTP POST requests

For a small applications this level of organization may be excessive, however, for larger projects splitting responsibilities into separate directories and/or files can be helpful.

TypeScript files for back-end server may be transpiled via npm run script targets...

npm run ts-build-back-end

... which will output transpiled JavaScript files to the back-end directory

front-end/index.html served to web-browsers issuing HTTP GET requests at <hostname>/index.html, or <hostname>/
ts/front-end/assets/js/ directory contains JavaScript files for web-browsers to execute
ts/front-end/assets/js/index.ts defines how web-browsers should interact with back-end via HTTP POST requests, as well as how repose data should be displayed.

Currently the front-end code for web-browsers is not pretty, but is functional.

Contributing

Options for contributing to api-list-path and web-dev-examples

Forking

Start making a Fork of this repository to an account that you have write permissions for.

Add remote for fork URL. The URL syntax is git@github.com:<NAME>/<REPO>.git...

cd ~/git/hub/web-dev-examples/api-list-path

git remote add fork git@github.com:<NAME>/api-list-path.git

Commit your changes and push to your fork, eg. to fix an issue...

cd ~/git/hub/web-dev-examples/api-list-path


git commit -F- <<'EOF'
:bug: Fixes #42 Issue


**Edits**


- `<SCRIPT-NAME>` script, fixes some bug reported in issue
EOF


git push fork main

Note, the -u option may be used to set fork as the default remote, eg. git push -u fork main however, this will also default the fork remote for pulling from too! Meaning that pulling updates from origin must be done explicitly, eg. git pull origin main

Then on GitHub submit a Pull Request through the Web-UI, the URL syntax is https://github.com/<NAME>/<REPO>/pull/new/<BRANCH>

Note; to decrease the chances of your Pull Request needing modifications before being accepted, please check the dot-github repository for detailed contributing guidelines.

Sponsor

Thanks for even considering it!

Via Liberapay you may _{[![sponsor__shields_io__liberapay]][sponsor__link__liberapay]} on a repeating basis.

Regardless of if you're able to financially support projects such as api-list-path that web-dev-examples maintains, please consider sharing projects that are useful with others, because one of the goals of maintaining Open Source repositories is to provide value to the community.

Attribution

License

ExpressJS example server and client API
Copyright (C) 2020 S0AndS0

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, version 3 of the License.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

For further details review full length version of AGPL-3.0 License.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commits
.github		.github
back-end		back-end
front-end		front-end
ts		ts
.gitignore		.gitignore
LICENSE		LICENSE
package-lock.json		package-lock.json
package.json		package.json
tsconfig.back-end.json		tsconfig.back-end.json
tsconfig.front-end.json		tsconfig.front-end.json
tsconfig.json		tsconfig.json

License

web-dev-examples/api-list-path

Folders and files

Latest commit

History

Repository files navigation

Api List Path

Requirements

Quick Start

Usage

Setup Notes

Initialize Version Management

Development Dependencies

App Dependencies

Directory/File Structure

Overview

Contributing

Forking

Sponsor

Attribution

License

About

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Sponsor this project

Languages