stwno-mensa_api

A json- / grpc- / graphql-wrapper around the inofficial API for different canteens managed by the Studentenwerk Niederbayern/Oberpfalz.

The original 'API' is kind of unhandy, as it serves its weekly data in the CSV format and updates only weekly. To improve the handling for more simple applications, this wrapper allows RESTful routes and serves its data in the JSON format (and also provides a gRPC and GraphQL backend!).

You can check on their official site or Locations.json if your canteen is supported.

Table of contents

1. Build
2. Run
3. Usage
   • RESTful API
   • GraphQL
   • gRPC
4. Development
5. Acknowledges
6. License

Build

Clone repository:

$ git clone https://github.com/dotWee/stwno-mensa_api && cd stwno-mensa_api

Install dependencies:

$ npm install

Run

Start the application by executing $ npm run start:

$ npm run start
 
> stwno-mensa_api@3.0.0 start /Users/lukas/Git/Projects/Javascript/stwno-mensa_api
> node src/server.js
 
Updating local cache...
Webserver started on port: 3000
GRPC listening on port: 3001
 
See http://localhost:3000/api-docs for RESTful API docs
Or http://localhost:3000/graphql about GraphQL usage

Usage

This Node.js application is deployed to herokuapp:

• https://rgb-mensa-api.herokuapp.com/

RESTful-API

Checkout the API documentation generated by Swagger for informations on how to use the RESTful API (see the configuration file swagger.json, also hosted on Swagger-Hub).

Example path to get todays menu for the university canteen:

GET /api/items/regensburg-university/today

[
    {
    "name": "Karotten-Ingwer-Suppe",
    "date": "26.11.2018",
    "day": "monday",
    "category": "Suppe",
    "labels": [
      "V"
    ],
    "ingredients": [
      {
        "key": "3",
        "value": "mit Antioxidationsmittel"
      },
      {
        "key": "A",
        "value": "Gluten"
      },
      {
        "key": "AA",
        "value": "Weizen"
      },
      {
        "key": "I",
        "value": "Sellerie"
      }
    ],
    "price": {
      "students": "0,70",
      "employees": "0,90",
      "guests": "1,40"
    }
  }, ...
]

GraphQL

Beside the usual RESTful API, this application also provides a GraphQL service. From GraphQL's website:

GraphQL is a query language for your API, and a server-side runtime for executing queries by using a type system you define for your data. GraphQL isn't tied to any specific database or storage engine and is instead backed by your existing code and data.

You can play with its service by visiting rgb-mensa-api.herokuapp.com/graphql (or localhost:3000/graphql in case of local execution).

Example GraphQL query

Example response

{   ingredients(key: "5") {     value   }   menu(location: "uni", day: "monday") {     args {       location       day     }     count     items {       name       date       day       category       labels       ingredients {         key         value       }       price {         students         guests         employees       }     }   } }

{     "data": {         "ingredients": [{             "value": "geschwefelt"         }],         "menu": {             "args": {                 "location": "uni",                 "day": "monday"             },             "count": 1,             "items": [{                 "name": "Karotten-Ingwer-Suppe",                 "date": "26.11.2018",                 "day": "monday",                 "category": "Suppe",                 "labels": [                     "V"                 ],                 "ingredients": [{                         "key": "3",                         "value": "mit Antioxidationsmittel"                     },                     {                         "key": "A",                         "value": "Gluten"                     },                     {                         "key": "AA",                         "value": "Weizen"                     },                     {                         "key": "I",                         "value": "Sellerie"                     }                 ],                 "price": {                     "students": "0,70",                     "guests": "1,40",                     "employees": "0,90"                 }             }]         }     } }

gRPC

This application also supports access using the gRPC Framework with Google's Protocol Buffers as JSON alternative.

This is what the protocol configuration looks like (File schema.proto):

syntax = "proto3";
 
package stwno_mensa_api;
 
// The items service definition.
service Items {
  // Returns items
  rpc GetItems (ItemsRequest) returns (ItemsResponse) {}
}
 
// The items request, may containing arguments
message ItemsRequest {
  string location = 1;
  string day = 2;
}
 
// The items response
message ItemsResponse {
  Error error = 1;
  repeated Item items = 2;
}
 
message Item {
  string name = 1;
  string date = 2;
  string day = 3;
  string category = 4;
  repeated string labels = 5;
 
  message Ingredient {
    string key = 1;
    string value = 2;
  }
  repeated Ingredient ingredients = 6;
 
  message Price {
    string students = 1;
    string employees = 2;
    string guests = 3; 
  }
  Price price = 7;
}

Example client (using Node.js)

You can find an example client written in Node.js source code in clients/client_grpc.js.

For execution: Open a shell window and run $ npm run start to get the server running. Then, open another window and run $ node ./clients/client_grpc.js to perform some requests and print the responses.

Development

For local development, use $ npm run nodemon to work at the source code. The application will reload on code changes.

Acknowledges

This application is heavily inspired by @alexanderbazo's URMensa-JSON-API project.

License

Copyright (c) 2018 Lukas Wolfsteiner. This project is licensed under the GNU General Public License v3 public license:

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

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 General Public License for more details.

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