From 5e2454243bf5804e5c408b89cd5905dc3de5c6cd Mon Sep 17 00:00:00 2001 From: Tanner Collin Date: Sun, 28 Nov 2021 05:10:42 +0000 Subject: [PATCH] Begin markdown docs --- apiserver/docs/source/api.md | 50 ++ apiserver/docs/source/api.rst | 994 ------------------------- apiserver/docs/source/apioverview.rst | 82 -- apiserver/docs/source/conf.py | 12 +- apiserver/docs/source/dev_apiserver.md | 60 ++ apiserver/docs/source/index.rst | 1 + apiserver/docs/source/specs.rst | 120 --- 7 files changed, 121 insertions(+), 1198 deletions(-) create mode 100644 apiserver/docs/source/api.md delete mode 100644 apiserver/docs/source/api.rst delete mode 100644 apiserver/docs/source/apioverview.rst create mode 100644 apiserver/docs/source/dev_apiserver.md delete mode 100644 apiserver/docs/source/specs.rst diff --git a/apiserver/docs/source/api.md b/apiserver/docs/source/api.md new file mode 100644 index 0000000..498ff7a --- /dev/null +++ b/apiserver/docs/source/api.md @@ -0,0 +1,50 @@ +# Spaceport API + +The current API URL is: https://api.my.protospace.ca/ + +JSON is returned by all API responses including errors and HTTP response status +codes are to designate success and failure. + +Request bodies can be JSON or form data. + +All API routes require a trailing slash. This is a Django default and you'll get +a 301 redirect if you forget it. + +## Authentication + +Most API routes require authentication with a token. The token is returned on +registration and login. The token needs to be placed in the `Authorization` +request header like this: `Token `. + +**Example** + +Login request: + +``` +$ curl -d 'username=tanner.collin' -d 'password=supersecret' 'https://my.protospace.ca/rest-auth/login/' +``` + +Login response: + +``` +{"key":"1fb8ef73f118c5de1f9ba4939a76b3f3b0bc7444"} +``` + +Add the following header to requests: + +``` +Authorization: Token 1fb8ef73f118c5de1f9ba4939a76b3f3b0bc7444 +``` + +/user/ request: + +``` +curl -H 'Authorization: Token 1fb8ef73f118c5de1f9ba4939a76b3f3b0bc7444' 'https://my.protospace.ca/user/' +``` + +## API Routes + +API routes are not documented. They used to be but the utility for how much +effort it took was not worth it. + +Use your browser's network inspector to learn how the API works. diff --git a/apiserver/docs/source/api.rst b/apiserver/docs/source/api.rst deleted file mode 100644 index c50cabf..0000000 --- a/apiserver/docs/source/api.rst +++ /dev/null @@ -1,994 +0,0 @@ -API -=== - -.. contents:: :depth: 3 - -User ----- - -Registration -++++++++++++ - -.. http:post:: /registration/ - - Register an account on Spaceport. Only works from Protospace's IP addresses. - - :json first_name: - :json last_name: - :json username: Should be ``first.last`` - :json password1: - :json password2: - :json email: - :json boolean existing_member: If ``true``, will link old portal objects based - on email match. - :json bypass_code: allows them to register from outside Protospace - - **Example response**: - - .. sourcecode:: json - - {"key":"1fb8ef73f118c5de1f9ba4939a76b3f3b0bc7444"} - -Login -+++++ - -.. http:post:: /rest-auth/login/ - - Log in with username and password, responds with auth token. - - Put the token in the ``Authorization`` HTTP header like ``Token `` to - authenticate. - - :json username: - :json password: - - **Example request**: - - .. sourcecode:: bash - - $ curl \ - -d '{"username":"tanner.tester", "password":"supersecret"}' \ - -H "Content-Type: application/json" \ - -X POST \ - http://api.spaceport.dns.t0.vc/rest-auth/login/ - - **Example response**: - - .. sourcecode:: json - - {"key":"1fb8ef73f118c5de1f9ba4939a76b3f3b0bc7444"} - -Full User -+++++++++ - -.. http:get:: /user/ - - Retrieve an object with complete user data. - - :requestheader Authorization: ``Token `` - - **Example request**: - - .. sourcecode:: bash - - $ curl \ - -H "Authorization: Token 1fb8ef73f118c5de1f9ba4939a76b3f3b0bc7444" \ - https://api.spaceport.dns.t0.vc/user/ - - **Example response**: - - .. sourcecode:: json - - { - "id": 113, - "username": "tanner.tester", - "member": { - "id": 1685, - "status": "Current", - "email": "text", - "phone": "text", - "street_address": "text", - "city": "text", - "postal_code": "text", - "old_email": "text", - "photo_large": "uuid.jpg", - "photo_medium": "uuid.jpg", - "photo_small": "uuid.jpg", - "member_forms": "uuid.pdf", - "set_details": true, - "first_name": "Tanner", - "last_name": "Collin", - "preferred_name": "Tanner", - "emergency_contact_name": "text", - "emergency_contact_phone": "text", - "birthdate": null, - "is_minor": false, - "guardian_name": "", - "public_bio": "", - "private_notes": "", - "is_director": false, - "is_staff": true, - "is_instructor": false, - "expire_date": "2020-01-23", - "current_start_date": "2016-08-23", - "application_date": "2016-08-23", - "vetted_date": "2016-09-27", - "paused_date": null, - "monthly_fees": 50, - "user": 113 - }, - "transactions": [ - { - "id": 31783, - "account_type": "PayPal", - "info_source": "PayPal IPN", - "member_name": "Tanner Collin", - "date": "2019-12-22", - "member_id": 1685, - "amount": "50.00", - "reference_number": "text", - "memo": "text", - "number_of_membership_months": null, - "payment_method": null, - "category": "Memberships:PayPal Payments", - "user": 113, - "recorder": null - } - ], - "cards": [ - { - "id": 392, - "member_id": 1685, - "card_number": "text", - "notes": "Tanner Collin", - "last_seen_at": "2020-01-20", - "active_status": "card_active", - "user": 113 - } - ], - "training": [ - { - "id": 971, - "session": { - "id": 11073, - "student_count": 20, - "course_name": "Metal: Metal Cutting & Manual Lathe", - "instructor_name": "John W", - "datetime": "2016-09-17T16:00:00Z", - "course": 281, - "is_cancelled": false, - "old_instructor": "John W", - "cost": "10.00", - "max_students": null, - "instructor": null - }, - "member_id": 1685, - "attendance_status": "Confirmed", - "sign_up_date": null, - "paid_date": null - } - ], - "is_staff": true - } - - :json is_staff: Set in Django's admin panel. You'll need to set this for the - first user so that you can assign more admins. - :json member.is_staff: Set by directors / staff in UI. - -Change Password -+++++++++++++++ - -.. http:post:: /password/change/ - - :json old_password: - :json password1: - :json password2: - - **Example response**: - - .. sourcecode:: json - - {"detail":"New password has been saved."} - - -Reset Password -++++++++++++++ - -.. http:post:: /password/reset/ - - :json email: - - **Example response**: - - .. sourcecode:: json - - {"detail":"Password reset e-mail has been sent."} - - -Confirm Reset -+++++++++++++ - -.. http:post:: /password/reset/confirm/ - - The uid and token are found in the email message: - - ``/password/reset/confirm/{uid}/{token}/`` - - :json uid: - :json token: - :json new_password1: - :json new_password2: - - **Example response**: - - .. sourcecode:: json - - {"detail":"Password has been reset with the new password."} - - -Members -------- - -Member Details -++++++++++++++ - -.. http:get:: /members/(id)/ - - Retrieve an object with member details. Users can only view themselves, - admins can view anyone. - - :param id: - - :requestheader Authorization: ``Token `` - - **Example request**: - - .. sourcecode:: bash - - $ curl \ - -H "Authorization: Token 1fb8ef73f118c5de1f9ba4939a76b3f3b0bc7444" \ - https://api.spaceport.dns.t0.vc/members/1685/ - - **Example response**: - - .. sourcecode:: json - - { - "id": 1685, - "status": "Current", - "email": "text", - "phone": "text", - "street_address": "text", - "city": "text", - "postal_code": "text", - "old_email": "text", - "photo_large": "uuid.jpg", - "photo_medium": "uuid.jpg", - "photo_small": "uuid.jpg", - "member_forms": "uuid.pdf", - "set_details": true, - "first_name": "Tanner", - "last_name": "Collin", - "preferred_name": "Tanner", - "emergency_contact_name": "text", - "emergency_contact_phone": "text", - "birthdate": null, - "is_minor": false, - "guardian_name": "", - "public_bio": "", - "private_notes": "", - "is_director": false, - "is_staff": false, - "is_instructor": false, - "expire_date": "2020-01-23", - "current_start_date": "2016-08-23", - "application_date": "2016-08-23", - "vetted_date": "2016-09-27", - "paused_date": null, - "monthly_fees": 50, - "user": 113 - } - - :json member.old_email: From old portal import, used to claim member when - registering. - :json \*.member_id: From old portal import, used as a hint to link the - object to users when they claim their old member. - :json photo\_\*: Should be served by nginx on the ``static`` subdomain. Refers - to photo filenames in the ``apiserver/data/static`` directory. - :json member_forms: Should be served by nginx on the ``static`` subdomain. - :json status: Derived by subtracting today's date from expire_date. More - than one month: Prepaid, less than one month: Current, less than one - month behind: Due, more than one month behind: Overdue. Members more - than three months behind are paused. Value stored to make searching - faster. - :json expire_date: Derived by summing all member transaction's - number_of_membership_months and adding to member's current_start_date. - Value stored to make searching faster. - -.. http:post:: /members/ - - Not allowed. Object is created upon registration. - -Edit Member Details -+++++++++++++++++++ - -.. http:patch:: /members/(id)/ - - Set member details. - - Member PDF forms will automatically be regenerated on any change. - - **Users** - - Can only set certain fields of their own member. - - :form photo: A member photo that will be turned into different sizes and - referred to by photo_large, photo_medium, photo_small. - - :json email: - :json phone: - :json street_address: - :json city: - :json postal_code: - :json boolean set_details: Set true if they've filled out the new member - form on sign up so the UI stops showing it. - :json preferred_name: What's shown throughout the UI. - :json emergency_contact_name: optional - :json emergency_contact_phone: optional - :json birthdate: optional, YYYY-MM-DD - :json boolean is_minor: - :json guardian_name: optional - :json public_bio: optional - :json private_notes: optional - - **Admins** - - Can modify any member. Above fields, plus: - - :json first_name: - :json last_name: - :json boolean is_instructor: Able to create and edit courses and sessions. - :json application_date: When they applied to Protospace, YYYY-MM-DD. - :json current_start_date: When to start counting their membership dues from. - Would only differ from application_date for accounting reasons, YYYY-MM-DD. - :json vetted_date: YYYY-MM-DD - :json monthly_fees: used to match PayPal transactions - - :requestheader Authorization: ``Token `` - - **Response** - - Same as GET. - -.. http:put:: /members/(id)/ - - Same as PATCH but requires all fields present. - -Pausing / Unpausing Member -++++++++++++++++++++++++++ - -.. http:post:: /members/(id)/pause/ - /members/(id)/unpause/ - - Pause or unpause a membership. Can only be done by admins. - - Pausing a member sets their paused_date to today. Their cards aren't sent to - the door controller. Their expire_date and status won't be evaluated daily - any longer. - - Unpausing a member sets their current_start_date to their paused_date. Their - paused_date is then set to null. They will be Due. Their active cards will - begin working again. - - :param id: - - :requestheader Authorization: ``Token `` - - **Response** - - :status 200: - - -Search ------- - -Searching -+++++++++ - -.. http:post:: /search/ - - Perform a search for members' names. - - Exact prefix matches are returned first, then exact substring matches, then - fuzzy matches. - - POST is used because our auth header causes a pre-flight request. These - can't be cached if the URL keeps changing like with query params. Using the - request body for the query prevents an OPTIONS request per keystroke. - - Designed to be fast enough for incremental search. - - An empty search returns the most recently vetted members. - - :json q: The search query. - :json int seq: An integer that gets returned with the search results. - Useful to prevent responses that arrive out-of-order from being - displayed as search results. ``event.timeStamp()`` is a good value to use. - - :requestheader Authorization: ``Token `` - - **Example response**: - - .. sourcecode:: json - - { - "seq": 12345, - "results": [ - { - "member": { - "id": 1685, - "preferred_name": "Tanner", - "last_name": "Collin", - "status": "Current", - "current_start_date": "2016-08-23", - "photo_small": "uuid.jpg", - "photo_large": "uuid.jpg" - } - }, - { - "member": { - "id": 1993, - "preferred_name": "Tanner", - "last_name": "text", - "status": "Former Member", - "current_start_date": null, - "photo_small": null, - "photo_large": null - } - } - ] - } - -Search Result -+++++++++++++ - -.. http:get:: /search/(id)/ - - Returns a specific search result. Users can see a partial member object. Admins can see the full member, cards, and transactions. - - :param id: - - :requestheader Authorization: ``Token `` - - **Example user response**: - - .. sourcecode:: json - - { - "member": { - "id": 1685, - "preferred_name": "Tanner", - "last_name": "Collin", - "status": "Current", - "current_start_date": "2016-08-23", - "photo_small": "uuid.jpg", - "photo_large": "uuid.jpg" - } - } - - **Example admin response**: - - Truncated. - - .. sourcecode:: json - - { - "member": {}, - "cards": [], - "transactions": [], - } - - -Transactions ------------- - -Transaction Details -+++++++++++++++++++ - -.. http:get:: /transactions/(id)/ - - Retrieve a transaction. Users can only view their own. Admins can view - anyone's. - - :param id: - - :requestheader Authorization: ``Token `` - - **Example response**: - - .. sourcecode:: json - - { - "id": 40720, - "account_type": "PayPal", - "info_source": "PayPal IPN", - "member_id": 1685, - "member_name": "Tanner Collin", - "date": "2020-01-30", - "report_type": null, - "amount": "100.00", - "reference_number": "234236326", - "memo": "1685, text, email, etc", - "number_of_membership_months": 2, - "payment_method": "instant", - "category": "Memberships:PayPal Payments", - "paypal_txn_id": "234236326", - "paypal_payer_id": "123ABCDEFGHIJ", - "report_memo": null, - "user": 2, - "recorder": null - } - - -Reported Transactions -+++++++++++++++++++++ - -.. http:get:: /transactions/ - - Retrieve a list of reported transactions. Admins only. - - Reported transactions are one with a report_type not null. - - :requestheader Authorization: ``Token `` - - **Example response** - - Truncated. - - .. sourcecode:: json - - { - "count": 6, - "next": null, - "previous": null, - "results": [ - { - "id": 40715, - "etc": "...", - }, - { - "id": 40716, - "etc": "...", - }, - { - "id": 40717, - "etc": "...", - } - ] - } - -Create Transaction -++++++++++++++++++ - -.. http:post:: /transactions/ - - Add a transaction to a member. Admins only. - - :json date: YYYY-MM-DD - :json int member_id: Which member the transaction belongs to. - :json decimal amount: Positive is money going to Protospace, XX.XX. - :json account_type: One of: ``Interac``, ``TD Chequing``, ``Dream Pmt``, - ``PayPal``, ``Square Pmt``, ``Member``, ``Clearing``, ``Cash`` - :json info_source: One of: ``Web``, ``DB Edit``, ``System``, ``Receipt or Stmt``, ``Quicken - Import``, ``PayPal IPN``, ``Auto``, ``Nexus DB Bulk``, ``IPN Trigger``, - ``Intranet Receipt``, ``Automatic``, ``Manual`` - :json number_of_membership_months: Used when calculating member status and - expire date, optional. - :json reference_number: optional - :json memo: optional - :json payment_method: optional - :json category: optional - :json report_type: One of: ``null``, ``Unmatched Member``, ``Unmatched Purchase``, - ``User Flagged`` - :json report_memo: The reason for the report, optional. - - :requestheader Authorization: ``Token `` - - **Response** - - Same as GET. - -Edit Transaction -++++++++++++++++++ - -.. http:patch:: /transactions/(id) - - Same fields as POST. Admins only. - - :param id: The transaction's ID. - - :requestheader Authorization: ``Token `` - -.. http:put:: /transactions/(id)/ - - Same as PATCH but requires all fields present. - -Report Transaction -++++++++++++++++++ - -.. http:post:: /transactions/(id)/report/ - - Allows users to report their own transactions for review. - - ``report_type`` will automatically be set to ``User Flagged``. - - :param id: The transaction's ID. - - :json report_memo: The reason for the report, required. - - :requestheader Authorization: ``Token `` - - **Response** - - :status 200: - - -Courses -------- - -.. http:get:: /courses/ - - List of all courses, ordered by which has most upcoming session. - - Truncated. - - .. sourcecode:: json - - { - "count": 59, - "next": null, - "previous": null, - "results": [ - { - "id": 261, - "name": "Woodworking Tools 1: Intro to Saws" - }, - { - "id": 321, - "name": "Laser: Trotec Course" - } - ] - } - -.. http:get:: /courses/(id)/ - - :param id: The course's ID. - - .. sourcecode:: json - - { - "id": 417, - "sessions": [ - { - "id": 12375, - "student_count": 11, - "course_name": "HAM Radio Introduction", - "instructor_name": "Pat S", - "datetime": "2019-01-24T02:00:00Z", - "course": 417, - "is_cancelled": false, - "old_instructor": "Pat S", - "cost": "0.00", - "max_students": null, - "instructor": null - } - ], - "name": "HAM Radio Introduction", - "description": "text", - "is_old": true - } - - :json boolean is_old: True if imported from old portal. - :json description: Text separated by \\n if is_old, otherwise HTML. - -.. http:post:: /courses/ -.. http:put:: /courses/(id)/ -.. http:patch:: /courses/(id)/ - - Instructors and admins only. - - :param id: The course's ID. - - :json name: - :json boolean is_old: - :json description: - - :requestheader Authorization: ``Token `` - - - -Sessions --------- - - Classes are called sessions in the API because of old portal models - and "class" keyword conflict. - - A session (class) belongs to a course and has a specific date, time, - instructor, and cost. - -.. http:get:: /sessions/ - - List of the 20 next sessions. - - Truncated. - - .. sourcecode:: json - - { - "count": 20, - "next": null, - "previous": null, - "results": [ - { - "id": 13476, - "student_count": 0, - "course_name": "CAD: Introduction to 3D CAD (Fusion)", - "instructor_name": "Mike M", - "datetime": "2020-01-18T16:30:00Z", - "course": 253, - "is_cancelled": false, - "old_instructor": "Mike M", - "cost": "0.00", - "max_students": null, - "instructor": null - } - ] - } - - :json student_count: Number of students registered, excluding withdrawn. - - -.. http:get:: /sessions/(id)/ - - :param id: The course's ID. - - .. sourcecode:: json - - { - "id": 13476, - "student_count": 0, - "course_name": "CAD: Introduction to 3D CAD (Fusion)", - "instructor_name": "Mike M", - "datetime": "2020-01-18T16:30:00Z", - "course": 253, - "students": [], - "is_cancelled": false, - "old_instructor": "Mike M", - "cost": "0.00", - "max_students": null, - "instructor": null - } - -.. http:post:: /sessions/ -.. http:put:: /sessions/(id)/ -.. http:patch:: /sessions/(id)/ - - Instructors and admins only. - - :param id: The session's ID. - - :json datetime: UTC ISO 8601, YYYY-MM-DDTHH:MM:SSZ - :json int course: ID of the course it belongs to. - :json boolean is_cancelled: Only for display. - :json decimal cost: 0 if free. - :json int max_students: optional - - :requestheader Authorization: ``Token `` - - -Training --------- - - A training object is created when a member registers for a session (class). - -.. http:get:: /training/(id)/ - - Retrieve a training object. Users can only view their own. Instructors can - view their students'. Admins can view anyone's. - - :param id: The training object's ID. - - :requestheader Authorization: ``Token `` - - .. sourcecode:: json - - { - "id": 971, - "attendance_status": "Confirmed", - "session": 11073, - "student_name": "Tanner Collin", - "member_id": 1685, - "sign_up_date": null, - "paid_date": null, - "user": 113 - } - -.. http:post:: /training/ - - Register for a session (class). - - **Users** - - :json attendance_status: One of: ``Waiting for payment``, ``Withdrawn`` - :json int session: The session (class) to register for. - - **Instructors and Admins** - - :json attendance_status: One of: ``Waiting for payment``, ``Withdrawn``, - ``Rescheduled``, ``No-show``, ``Attended``, ``Confirmed`` - :json int session: The session (class) to register for. - - :requestheader Authorization: ``Token `` - -.. http:put:: /training/(id)/ -.. http:patch:: /training/(id)/ - - Edit attendance status. - - Same params as POST. - - :requestheader Authorization: ``Token `` - - -Cards ------ - - Cards are sent to Protospace's door controllers to grant access to the - building. Only active cards of unpaused members are sent. - -.. http:get:: /cards/(id)/ - - Retrieve a card. Users can only view their own, admins can view anyone's. - - :param id: The card object's ID. - - :requestheader Authorization: ``Token `` - - .. sourcecode:: json - - { - "id": 392, - "card_number": "text", - "member_id": 1685, - "active_status": "card_active", - "notes": "Tanner Collin", - "last_seen_at": "2020-01-20", - "user": 113 - } - -.. http:post:: /cards/ -.. http:put:: /cards/(id)/ -.. http:patch:: /cards/(id)/ -.. http:delete:: /cards/(id)/ - - Admins only. Don't change the status when pausing a member, paused member's - cards are filtered out automatically. - - :param id: The card object's ID. - - :json card_number: Usually a 10 character hex string. - :json int member_id: Which member the card belongs to. - :json active_status: One of: ``card_blocked``, ``card_inactive``, - ``card_member_blocked``, ``card_active`` - :json notes: optional - - :requestheader Authorization: ``Token `` - - -Door ----- - - Private route that the door controllers should poll for a list of cards - allowed to scan into the building. - -.. http:get:: /door/ - - List all active cards of unpaused members. - - Authorization with the door API token set in secrets.py is required. - - Use "Bearer" instead of "Token" like in the other routes. - - :requestheader Authorization: ``Bearer `` - - **Example response** - - Truncated. - - .. sourcecode:: json - - { - "0000001234": "Tanner C (1685)", - "000000ABCD": "Tanner C (1685)", - } - - :json key: The dict keys are the card numbers. - :json value: Member's name and ID. - -.. http:post:: /door/(card_number)/seen/ - - Update card's last_seen_at to today. - - This doesn't do any fancy logging yet. - - :param card_number: Usually a 10 character hex string. - - No authentication required. - - -Ping ----- - -.. http:post:: /ping/ - - Does nothing except check if a user's auth token is still valid. - - :requestheader Authorization: ``Token `` - - **Response** - - :status 200: - - -Stats ------ - - Public route that returns stats about Spaceport and Protospace. - -.. http:get:: /stats/ - - Retrieve the stats object. This is very inexpensive, so feel free to call frequently. - - **Example response** - - .. sourcecode:: json - - { - "bay_108_temp": 22.1, - "bay_110_temp": 22.5, - "card_scans": 7, - "last_card_change": 1595844608.7921524, - "green_count": 153, - "member_count": 191, - "paused_count": 1071, - "minecraft_players": ["tanner6"], - "next_clean": "2020-08-08T16:00:30Z", - "next_meeting": "2020-08-20T01:00:20Z", - "track": { - "FRICKIN-LASER": 1595882018.228888, - "TROTECS300": 1595797812.8726459 - } - } - - :json bay_108_temp: Celsius temperature of bay 108. - :json bay_110_temp: Celsius temperature of bay 110. - :json card_scans: Number of unique card scans that day. - :json last_card_change: Time of last update to member cards. - :json green_count: Number of current and prepaid members. - :json member_count: Total number of Protospace members. - :json paused_count: Number of expired (old) members. - :json minecraft_players: A list of players currently on the Minecraft server. - :json next_clean: UTC datetime of next monthly clean. - :json next_meeting: UTC datetime of next member's meeting. - :json track: A dictionary of computer names and their last ping's epoch time. - - -.. http:post:: /stats/track/ - - Update the time at which a computer was last seen. - - Used to track when the lasers are in use. - - :param name: The computer's hostname. - - No authentication required. diff --git a/apiserver/docs/source/apioverview.rst b/apiserver/docs/source/apioverview.rst deleted file mode 100644 index 2594eab..0000000 --- a/apiserver/docs/source/apioverview.rst +++ /dev/null @@ -1,82 +0,0 @@ -API Overview -============ - -The current API URL is: https://api.spaceport.dns.t0.vc/ - -The Spaceport API uses REST. JSON is returned by all API responses including -errors and HTTP response status codes are to designate success and failure. - -Request bodies can be JSON or form data. - -All API routes require a trailing slash. This is a Django default and you'll get -a 301 redirect if you forget it. - -Authentication --------------- - -All API routes require authentication with a token. The -token is returned on registration and login. The token needs to be placed in the -``Authorization`` request header like this: ``Token ``. - -**Example** - -Login response: - -.. sourcecode:: json - - {"key":"1fb8ef73f118c5de1f9ba4939a76b3f3b0bc7444"} - -Add the following header to requests: - -.. sourcecode:: text - - Authorization: Token 1fb8ef73f118c5de1f9ba4939a76b3f3b0bc7444 - - -Quick Reference ---------------- - -.. http:post:: /registration/ -.. http:post:: /rest-auth/login/ -.. http:get:: /user/ -.. http:post:: /password/change/ -.. http:post:: /password/reset/ -.. http:post:: /password/reset/confirm/ -.. http:get:: /members/(id)/ -.. http:post:: /members/ -.. http:patch:: /members/(id)/ -.. http:put:: /members/(id)/ -.. http:post:: /members/(id)/pause/ -.. http:post:: /members/(id)/unpause/ -.. http:post:: /search/ -.. http:get:: /search/(id)/ -.. http:get:: /transactions/(id)/ -.. http:get:: /transactions/ -.. http:post:: /transactions/ -.. http:patch:: /transactions/(id) -.. http:put:: /transactions/(id)/ -.. http:post:: /transactions/(id)/report/ -.. http:get:: /courses/ -.. http:get:: /courses/(id)/ -.. http:post:: /courses/ -.. http:put:: /courses/(id)/ -.. http:patch:: /courses/(id)/ -.. http:get:: /sessions/ -.. http:get:: /sessions/(id)/ -.. http:post:: /sessions/ -.. http:put:: /sessions/(id)/ -.. http:patch:: /sessions/(id)/ -.. http:get:: /training/(id)/ -.. http:post:: /training/ -.. http:put:: /training/(id)/ -.. http:patch:: /training/(id)/ -.. http:get:: /cards/(id)/ -.. http:post:: /cards/ -.. http:put:: /cards/(id)/ -.. http:patch:: /cards/(id)/ -.. http:delete:: /cards/(id)/ -.. http:get:: /door/ -.. http:post:: /door/(card_number)/seen/ -.. http:post:: /ping/ -.. http:get:: /stats/ -.. http:post:: /stats/track/ diff --git a/apiserver/docs/source/conf.py b/apiserver/docs/source/conf.py index 9d5d6ea..4ccad33 100644 --- a/apiserver/docs/source/conf.py +++ b/apiserver/docs/source/conf.py @@ -14,6 +14,7 @@ # import sys # sys.path.insert(0, os.path.abspath('.')) +from recommonmark.parser import CommonMarkParser # -- Project information ----------------------------------------------------- @@ -28,10 +29,17 @@ author = 'Tanner Collin' # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx_rtd_theme', - 'sphinxcontrib.httpdomain', + 'recommonmark', ] +source_suffix = ['.rst', '.md'] + +source_parsers = { + '.md': 'CommonMarkParser', +} + +known_url_schemes = ['http', 'https'] + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/apiserver/docs/source/dev_apiserver.md b/apiserver/docs/source/dev_apiserver.md new file mode 100644 index 0000000..ddb5dae --- /dev/null +++ b/apiserver/docs/source/dev_apiserver.md @@ -0,0 +1,60 @@ +# API Server Development Setup + +This guide assumes you are using Debian GNU/Linux 10 or Ubuntu 20.04 LTS. If you +aren't, just spin up a VPN with the correct version. Things break if you don't. + +## Install Dependencies + +``` +$ sudo apt update +$ sudo apt install build-essential python3 python3-dev libffi-dev python3-pip python3-virtualenv memcached git +``` + +Clone the repo. Skip this step if you already have it: + +``` +$ git clone https://github.com/Protospace/spaceport.git +``` + +Set up Python: + +``` +$ cd spaceport/apiserver/ +$ python3 -m virtualenv -p python3 env +$ source env/bin/activate +(env) $ pip install -r requirements.txt +``` + +Copy the secrets file and optionally fill out values depending on which +[[integrations]] you wish to enable. + +``` +(env) $ cp apiserver/secrets.py.example apiserver/secrets.py +(env) $ sensible-editor apiserver/secrets.py # optional +``` + +## Initialize Database + +Set up the database: + +``` +(env) $ python manage.py makemigrations +(env) $ python manage.py makemigrations api +(env) $ python manage.py migrate +``` + +Create a super user so you can manage who's director or staff: + +``` +(env) $ python manage.py createsuperuser --email admin@example.com --username admin +``` + +## Running + +Run the development server: + +``` +$ source env/bin/activate +(env) $ DEBUG=true python manage.py runserver +``` + diff --git a/apiserver/docs/source/index.rst b/apiserver/docs/source/index.rst index 153316a..918977d 100644 --- a/apiserver/docs/source/index.rst +++ b/apiserver/docs/source/index.rst @@ -15,3 +15,4 @@ Spaceport Documentation apioverview api ldap + dev_apiserver diff --git a/apiserver/docs/source/specs.rst b/apiserver/docs/source/specs.rst deleted file mode 100644 index fd7ed97..0000000 --- a/apiserver/docs/source/specs.rst +++ /dev/null @@ -1,120 +0,0 @@ -Feature Specs -============= - -This is an outline of current and future features of Spaceport. - -Plain - Implemented - -Bold - Not yet implemented - - -Web Client ----------- - -- Home - - - Login - - Sign up - - - Register a new account - - Claim an old account on the portal - - Profile - - - Photo - - Status - - Details - - Application forms - - Latest transactions - - Public bio - - Private notes - - Quick links - - Stats - - - Next meetings - - Member counts - - Graphs of member counts - - Bay temperatures - - Minecraft server players -- Account settings - - - Edit member details - - Change password - - Log out from everywhere - - **Add custom CSS** -- Transactions - - - View list of transactions - - View transaction details - - Report an error in transaction - - Admins can edit transactions -- Paymaster - - - Buy snacks, pop, coffee - - Pay member dues - - Pay for locker storage - - Donate - -- Training - - - View list of training -- Cards - - - View list of access cards - - View door alarm code + wifi pass - - View API key -- Member list - - - Search for members by name, email, or ID - - View member photo, status, and joined date -- Admin member details - - - View all of a member's details - - Edit member details - - Make member an instructor - - Pause / unpause member - - View member's application forms - - View member cards - - Edit member cards - - View member transactions - - Edit member transactions -- Course list - - - View list of courses - - View course details - - View list of classes for a course - -- Instructor course list - - - Add a new course - - Edit course details - - Create a class for a course -- Class list - - - View upcoming classes - - View recent classes - - View class details - - Sign up for a course - - Pay for course with paypal - - Withdraw from a course -- Instructor class list - - - Edit class details - - **Add a custom note for a class** - - Mark off students' attendance - - View students' emails - - Print attendance sheet -- Transporter - - - Public paste bin to share text -- Admin Page - - - View recent backup times - - View all database changes -- Admin Transaction list - - - View reported transactions - - Correct reported transactions - - View all transactions by month -