{"id":13419199,"url":"https://github.com/loentar/ngrest","last_synced_at":"2025-03-15T05:30:27.045Z","repository":{"id":64430008,"uuid":"47983339","full_name":"loentar/ngrest","owner":"loentar","description":"Fast and easy C++ RESTful WebServices framework","archived":false,"fork":false,"pushed_at":"2022-01-24T19:36:18.000Z","size":851,"stargazers_count":465,"open_issues_count":15,"forks_count":95,"subscribers_count":30,"default_branch":"master","last_synced_at":"2024-07-31T22:46:14.879Z","etag":null,"topics":["json","rest","restful-webservices","server"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/loentar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-12-14T15:25:46.000Z","updated_at":"2024-07-22T13:45:13.000Z","dependencies_parsed_at":"2022-12-18T19:01:01.664Z","dependency_job_id":null,"html_url":"https://github.com/loentar/ngrest","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loentar%2Fngrest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loentar%2Fngrest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loentar%2Fngrest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loentar%2Fngrest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/loentar","download_url":"https://codeload.github.com/loentar/ngrest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243690121,"owners_count":20331725,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json","rest","restful-webservices","server"],"created_at":"2024-07-30T22:01:12.661Z","updated_at":"2025-03-15T05:30:26.671Z","avatar_url":"https://github.com/loentar.png","language":"C++","funding_links":[],"categories":["TODO scan for Android support in followings"],"sub_categories":[],"readme":"# ngrest\n\n[![Build Status](https://travis-ci.org/loentar/ngrest.png?branch=master)](https://travis-ci.org/loentar/ngrest)\n\nngrest is a simple C++ REST framework. It has small footprint, [fast](https://github.com/loentar/ngrest/wiki/Benchmark-results) and very easy in use.\n\nngrest allow you to deploy C++ RESTful webservices under [Apache2](https://github.com/loentar/ngrest/wiki/Deploy-ngrest-under-Apache2-Web-Server), [Nginx](https://github.com/loentar/ngrest/wiki/Deploy-ngrest-under-Nginx) or under simple ngrest http server.\n\nngrest is written on C++11 and uses CMake for build.\n\nDocumentation and how-to's are available from [Wiki](https://github.com/loentar/ngrest/wiki).\n\n## Quick tour\n\n### Hello world\n\nNo coding needed to make Hello world service working!\n\n```bash\nngrest create HelloWorld\ncd helloworld\nngrest\n```\n\nThat's all! Now you can browse service operations and try HelloWorld service using ngrest service tester: [http://localhost:9098/ngrest/service/HelloWorld](http://localhost:9098/ngrest/service/HelloWorld).\n\nUpon creation the test `echo` resource added to every service and by the address [http://localhost:9098/helloworld/echo?text=YOUR_TEXT](http://localhost:9098/helloworld/echo?text=YOUR_TEXT) this service will respond:\n\n```JSON\n{\"result\": \"Hi, YOUR_TEXT\"}\n```\n\n### Handling simple data types:\n\nngrest supports simple C++ data types:\n\n```C++\nclass Calculator: public ngrest::Service {\npublic:\n    int add(int a, int b) {\n        return a + b;\n    }\n\n    int sub(int a, int b) {\n        return a - b;\n    }\n};\n```\n\nTo the request [http://localhost:9098/Calculator/add?a=2\u0026b=3](http://localhost:9098/Calculator/add?a=2\u0026b=3) this service will respond:\n\n```JSON\n{\"result\":5}\n```\n\n### Handling complex data types\n\nngrest supports [complex C++ data types](https://github.com/loentar/ngrest/wiki/Using-complex-data-types) such as structures, enums, typedefs and STL containers:\n\n```C++\nstruct Pet {\n    enum class Species {\n        canine,\n        feline\n    };\n\n    Species species;\n    std::string name;\n    std::string birthday;\n};\n\nclass Pets: public ngrest::Service {\npublic:\n    std::list\u003cPet\u003e getPets() {\n        return std::list\u003cPet\u003e({{\n            Pet::Species::canine,\n            \"spot\",\n            \"Jan 1, 2010\"\n        },{\n            Pet::Species::feline,\n            \"puff\",\n            \"July 4, 2014\"\n        }});\n    }\n};\n```\n\nTo the request [http://localhost:9098/Pets/getPets](http://localhost:9098/Pets/getPets) this service will respond:\n\n```JSON\n{\"result\":[{\"species\":\"canine\",\"name\":\"spot\",\"birthday\":\"Jan 1, 2010\"},{\"species\":\"feline\",\"name\":\"puff\",\"birthday\":\"July 4, 2014\"}]}\n```\n\n### Setting up HTTP method and location\n\nTo set HTTP method and location special comments are used:\n\n```C++\n// *location: /notes\nclass Notes: public ngrest::Service {\npublic:\n    //! adds a new note\n    // *method: POST\n    // *location: /new\n    std::string add(const std::string\u0026 text);\n\n    //! gets all notes\n    // *location: /all\n    std::map\u003cstd::string, std::string\u003e getAll();\n\n    //! get a note by id\n    // *location: /{id}\n    std::string get(const std::string\u0026 id);\n\n    //! deletes a note by id\n    // *method: DELETE\n    // *location: /{id}\n    std::string remove(const std::string\u0026 id);\n};\n```\n\nPlease note, default method is `GET` and default location is equals to the name.\n\nThis will create a REST service on root path `/notes`. Also this will add four resources:\n\n\n|**Operation**|**Method**|**URL**|**Request**|**Response**|\n|-------------|----------|-------|-----------|------------|\n| add         | POST     | http://localhost:9098/notes/new | `{\"text\":\"Example text of the note\"}` | `{\"result\":\"d90638e1\"}` |\n| getAll      | GET      | http://localhost:9098/notes/all | | `{\"result\":[{\"d90638e1\":\"Example text of the note\"}]}` |\n| get         | GET      | http://localhost:9098/notes/d90638e1 | | `{\"result\":\"Example text of the note\"}` |\n| remove      | DELETE   | http://localhost:9098/notes/d90638e1 | | |\n\n\n## Install\n\nSupported OS are: Linux, Windows and Mac OS X. If you need support for another OS, please [create new issue](https://github.com/loentar/ngrest/issues/new).\n\nUnder Linux installation process is simple. To install ngrest, just open terminal and copy-paste:\n\n```bash\nwget -qO- http://bit.ly/ngrest | bash\n```\n\n[Installation guide with screenshots for Linux](https://github.com/loentar/ngrest/wiki/Installation-guide-with-screenshots)\n\n[Installation guide with screenshots for Windows](https://github.com/loentar/ngrest/wiki/Installation-guide-with-screenshots-Windows)\n\n[Installation guide with screenshots for Mac OS X](https://github.com/loentar/ngrest/wiki/Installation-guide-with-screenshots-OSX)\n\n**Notes:**\n\n1. If you don't have one of dependencies required, installer will ask you to enter your password to install it automatically. If you don't want this, press Ctrl+C and start this command: \"sudo apt-get install git cmake g++\". After apt-get finished, start the line above again.\n\n2. By default script installs `ngrest` wrapper into best location available. If you have `~/bin` directory in your search path `ngrest` wrapper will be installed into it. Else it will try to install into `/usr/local/bin/` and you will be prompted for your password to install. To override this behavior and forcibly install `ngrest` wrapper into `~/bin` please create `~/bin` directory and re-login. After re-login it should be added into `$PATH` automatically. If this does not happen, please add into your `~/.bashrc` or `~/.profile` a line: `export PATH=$PATH:$USER/bin`. Also you can export `USERINST` environment variable to something non-empty, install ngrest and re-login.\n\n## Create a new project\n\n[How to create and start project with screenshots](https://github.com/loentar/ngrest/wiki/Creating-and-starting-a-project-guide-with-screenshots)\n\nTo create a new project please open new terminal and enter:\n\n```\nngrest create \u003cproject_name\u003e\n```\n\nOr if you prefer to do not split the service to interface (.h) and implementation (.cpp) and develop the whole service within single `.hpp` file, add `-d hpp` option and ngrest will create hpp-style service(s) for you:\n\n```\nngrest create -d hpp \u003cproject_name\u003e\n```\n\n\nWhere `\u003cproject_name\u003e` is a name of your project and a service name.\n\nExample 1. Create project 'calculator' and a service 'Calculator':\n\n```\nngrest create Calculator\n```\n\nOptionally you can set up additional services and define it's namespaces.\n\nExample 2. Create project 'calc' and two services - 'org.example.Calculator' and 'org.example.DivService':\n\n```\nngrest create calc org.example.Calculator org.example.DivService\n```\n\n## Start the project\n\nWhen a project is generated, an `echo` operation is added into each service. It's only provided as fast example and can be safely removed when you write your own operations.\n\nYou can start your project right after it's created:\n\n```bash\ncd calc\nngrest\n```\n\nngrest wrapper will build your project and will start the server on default port.\n\nAfter server is started you can try your service operations: open a link located below the `To test your services try ngrest service tester:` message in your browser, click \"echo\" link, enter something into \"text\" field and press \"Submit\".\n\n\n## Implementing the service\n\nService's sources are located in `\u003cservicename\u003e/src/\u003cServiceName\u003e.h/cpp/hpp` files. To implement your service you must edit those files (QtCreator is a very good tool for that: open CMakeLists.txt from project's dir in QtCreator).\n\n\u003e While you change source code, you can leave project started. ngrest will detect any changes in source code and will try to build and to apply changes. In case of successful build ngrest will restart the server.\n\n\u003e If you faced with crash ngrest will try to trace the error using gdb and display the place of crash and program stack. To restart the server just modify your source code.\n\nExample. Add \"add\" operation into Calculator service:\n\n1) if you use hpp-style service insert these lines into `Calculator.hpp` before end of class:\n```C++\nint add(int a, int b)\n{\n    return a + b;\n}\n```\n\nto make your service class appear like this:\n\n```C++\nclass Calculator: public ngrest::Service\n{\npublic:\n    // ...\n    std::string echo(const std::string\u0026 text)\n    {\n        return \"Hi, \" + text;\n    }\n\n    int add(int a, int b)\n    {\n        return a + b;\n    }\n};\n```\n\n2) If you use h/cpp-style service, insert this line into `Calculator.h` before end of class:\n\n```C++\nint add(int a, int b);\n```\n\nto make your service class appear like this:\n\n```C++\nclass Calculator: public ngrest::Service\n{\npublic:\n    // ...\n    std::string echo(const std::string\u0026 text);\n\n    int add(int a, int b);\n};\n```\n\nand add implementation - append these lines into `Calculator.cpp`:\n\n```C++\nint Calculator::add(int a, int b)\n{\n    return a + b;\n}\n```\n\nAfter that, click on the service name in service tester to see and test new `add` operation.\n\n## Upgrade ngrest\n\nTo upgrade ngrest to the latest changeset from master branch type:\n\n`ngrest upgrade`\n\nIf you want to downgrade to specific commit, add commit hash as last argument, for example:\n\n`ngrest upgrade 3b78eee`\n\nIf there are any running projects it will be automatically rebuild and restarted.\n\n## Packages\n\nHere is a list of packages to extend ngrest functinality:\n\n|**Package**|**Repo URL**|**Description**|\n|-----------|------------|---------------|\n| loentar/ngrest-db | https://github.com/loentar/ngrest-db | Simple access to relational databases. |\n\n## TODO\n\n - support complex types in services tester\n - support of sessions/cookies\n - WADL support?\n\n## Support\n\nFeel free to ask ngrest related questions here on the [Google groups](https://groups.google.com/forum/#!forum/ngrest).\n\nThere also a chat on: [gitter.im/ngrest](https://gitter.im/ngrest)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floentar%2Fngrest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Floentar%2Fngrest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floentar%2Fngrest/lists"}