Skip to content

Commit

Permalink
docs: Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
ditsuke committed Jan 1, 2024
1 parent 1abd8a5 commit 879572f
Showing 1 changed file with 21 additions and 17 deletions.
38 changes: 21 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,28 +9,33 @@
[![Issues](https://img.shields.io/github/issues/ditsuke/go-amizone?logo=github)][issues]
![License](https://img.shields.io/github/license/ditsuke/go-amizone)

**go-amizone** is a simple and robust Go library and API server for the [Amizone](https://s.amizone.net) student portal.
This library is intended to be used as a self-hosted Go API or as an SDK in your Go application.
`go-amizone` is a minimalistic library that aims to provide a simple and robust API client for the
[Amizone](https://s.amizone.net) student portal. It is intended to be used as an API or as an SDK in your Go application.

> **Status:** Not actively maintained as of January 2024. Forks are welcome, but so are new maintainers
> for this canonical repository given they can commit to maintaining the quality and security
> standards of the project with proof of work.
## Inspiration

Amizone is _the_ student portal for [Amity University](https://www.amity.edu/). It's indispensable for students to
access their grades, attendance, class schedule and other information. The catch: it's buggy, slow and goes down all the
time! Students have made a slew of alternative apps and tools to access the portal over the years -- many of them mobile
apps, but also arguably better approaches like the excellent [monday-api][monday-api] bot by [@0xSaurabh][0xSaurabh]
(my initial inspiration!)
(the inspiration for this project!).

**But why go-amizone?** Because I wanted a simple, lean and robust API client for Amizone to develop an application
of my own and no existing solution seemed good enough. With this, I set out to develop something everyone (including me)
could use to build their own projects around the portal. While `go-amizone` is written in Go (_duh_), it has a WIP
OpenAPI documented API server which enables autogenerated SDKs for any language under the sun!
**But why go-amizone then?** I went looking for a lean API / SDK for Amizone and couldn't find one that was good enough.
I set out to build something that I could use for my own projects around the portal, and that others could use
too. Something that would last and be easy to maintain, integrate into projects across languages and form factors.
Now while `go-amizone` is written in Go, it has both a gRPC and REST API server which enables autogenerated SDKs for
any language under the sun! For more information, check out the [API Server](#api-server) section below.

## Completeness

`go-amizone` is far from complete. While its completely possible to use in applications today, there are no
guarantees yet for a stable API, which will come around with the 1.0 stable release. In the coming weeks I'll be adding
more features to drive the library closer to covering a more complete range of the data and features the Amizone
portal exposes.
`go-amizone` is far from complete, but it is stable and in use today. In fact, it's already being used in production by
over a 1000 students, through [Amibot](https://github.com/asetalias/amibot), [Amibot TG](https://github.com/asetalias/amibot-tg)
and other community projects. There is some indication of adoption by some mobile apps as well, developers are
encouraged to reach out and let me know!

## Installation

Expand All @@ -45,18 +50,17 @@ easily accessed on [pkg.go.dev][go-reference] or [godocs.io][godocs.io].
### API Server

The API Server offers a RESTful API through a single Go binary. It is intended to be used self-hosted on a VPS or a PaaS
like [Heroku][heroku], but I'll have a central deployment up soon so everyone can try out! To try locally, run:
like [Fly][fly], but I have a public instance running at https://amizone.fly.io. You can always host your own,
spinning up a new instance is as easy as running the following commands:

```shell
go install github.com/ditsuke/go-amizone/cmd/amizone-api-server@latest # installs the binary
amizone-api-server # runs the server
```

A docker image will be made available soon to make deployments easier.

## Postman collection
#### Postman collection

Check out this [Postman collection](https://www.postman.com/ditsuke/workspace/ditsuke) to test out our endpoints.
Check out this [Postman collection](https://www.postman.com/ditsuke/workspace/ditsuke) to test out our endpoints, both gRPC and REST.

## Contributing

Expand All @@ -72,6 +76,6 @@ Please read the [contribution guide](./CONTRIBUTING.md) for more information on
[issues]: https://github.com/ditsuke/amizone-go/issues
[go-reference]: https://pkg.go.dev/github.com/ditsuke/go-amizone
[coveralls]: https://coveralls.io/github/ditsuke/go-amizone?branch=main
[fly]: https://fly.io
[go-report-card]: https://goreportcard.com/report/github.com/ditsuke/go-amizone
[heroku]: https://www.heroku.com/
[godocs.io]: https://godocs.io/github.com/ditsuke/go-amizone

0 comments on commit 879572f

Please sign in to comment.