{"id":20038524,"url":"https://github.com/yahoo/parsec","last_synced_at":"2025-08-21T03:32:38.308Z","repository":{"id":46212945,"uuid":"63822526","full_name":"yahoo/parsec","owner":"yahoo","description":"A collection of libraries and utilities to simplify the process of building web service applications.","archived":false,"fork":false,"pushed_at":"2024-07-19T03:01:52.000Z","size":108522,"stargazers_count":34,"open_issues_count":5,"forks_count":20,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-08T03:31:20.640Z","etag":null,"topics":["build-tools","gradle","jersey2","mobile","parsec","rdl","web","web-services"],"latest_commit_sha":null,"homepage":"","language":"Java","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/yahoo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-07-20T23:55:33.000Z","updated_at":"2024-12-05T12:07:40.000Z","dependencies_parsed_at":"2024-11-13T10:40:30.170Z","dependency_job_id":null,"html_url":"https://github.com/yahoo/parsec","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/yahoo/parsec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Fparsec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Fparsec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Fparsec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Fparsec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yahoo","download_url":"https://codeload.github.com/yahoo/parsec/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Fparsec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271420520,"owners_count":24756582,"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","status":"online","status_checked_at":"2025-08-21T02:00:08.990Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["build-tools","gradle","jersey2","mobile","parsec","rdl","web","web-services"],"created_at":"2024-11-13T10:29:47.262Z","updated_at":"2025-08-21T03:32:37.901Z","avatar_url":"https://github.com/yahoo.png","language":"Java","readme":"# Parsec [![Build Status](https://app.travis-ci.com/yahoo/parsec.svg?branch=master)](https://app.travis-ci.com/yahoo/parsec)\n\nParsec is a collection of libraries and utilities built upon **Gradle** and **Jersey2**, with the reliance on [RDL](https://ardielle.github.io/).\nIt is designed to reduce the effort of building web service applications,\nallowing you to spend more quality time elsewhere. By using Parsec,\nthe grunt work is handled so you can concentrate on the logic and implementation side of development. More importantly,\nParsec also provides flexibility and abstraction such that you can easily enforce your own standard, and apply to the pipeline.\n\nParsec offers a standardized end-to-end solution to quickly bring web service applications from concept to production.\nThe goal of Parsec is to:\n\n* Provide a standard method for building APIs\n* Eliminate time spent in project and environment set up\n* Minimize time and effort spent on common repetitive tasks\n* Provide helper [libraries and utilities](https://github.com/yahoo/parsec-libraries) for common tasks\n* Reduce the learning curve and maintenance cost\n* Provide client for your web service\n\nIf you are building a new project with Java, Parsec is definitely a good starting point.\n\n## Getting Started\n\n### Requirements\n\n+ **Java 1.8**: check your jdk version using `$ java -version` or [download Java JDK 1.8](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)\n+ **Gradle (recommended version: \u003e2.4)**: check your gradle version using `$ gradle --v` or run\n\n `$ sudo brew install gradle` to install the latest gradle\n\nAfter having Java 1.8 and Gradle installed with the proper version, you must do a one time setup to allow you to create a\nParsec project without a build.gradle script.\n\n`$ vim ~/.gradle/init.gradle `, then enter the following code:\n\n```\ngradle.beforeProject { prj -\u003e\n   prj.apply from: 'https://raw.githubusercontent.com/yahoo/parsec/master/parsec-template-plugin/installation/apply.groovy'\n}\n\n```\n\n### Create a New Project\n\nTo create a new Parsec project, run:\n\n`$ gradle createParsecProject -PgroupId='your.group.name' -PartifactId='your_project_name'`\n\n**groupId** refers to the namespace of your package, while the **artifactId** is your project name.\nIf you do not specify the groupId or artifactId, you will be prompted to do so.\n\n### Create Schema\n\nYou need one or more RDL schema files to define your API specifications; they should be placed under src/main/rdl/ and be named as *.rdl.\nRDL is a machine-readable description of a schema that describes data types, as well as resources using those types.\n\nYou can start with this sample RDL file, save it as src/main/rdl/sample.rdl:\n\n```\nnamespace your.group.name;\nname sample;\nversion 1;\n\ntype User struct {\n    string name (x_not_null=\"groups=insert\", x_size=\"min=3,max=5,groups=update|insert\");\n    string occupation (x_not_null=\"groups=update\", x_size=\"min=4,groups=update|insert\");\n    int32 age;\n    string id (x_null=\"groups=insert\");\n}\n\nresource User GET \"/users/{id}\" {\n    int32 id;\n\n    expected OK;\n    exceptions {\n        ResourceError INTERNAL_SERVER_ERROR;\n        ResourceError BAD_REQUEST;\n        ResourceError UNAUTHORIZED;\n        ResourceError FORBIDDEN;\n    }\n}\n\nresource string POST \"/users\" {\n    User user (x_must_validate=\"insert\");\n\n    expected OK;\n    exceptions {\n        ResourceError INTERNAL_SERVER_ERROR;\n        ResourceError BAD_REQUEST;\n        ResourceError UNAUTHORIZED;\n        ResourceError FORBIDDEN;\n    }\n}\n\nresource string PUT \"/users/{id}\" {\n    int32 id ;\n\n    User user (x_must_validate=\"update\");\n\n    expected OK;\n    exceptions {\n        ResourceError INTERNAL_SERVER_ERROR;\n        ResourceError BAD_REQUEST;\n        ResourceError UNAUTHORIZED;\n        ResourceError FORBIDDEN;\n    }\n\n}\n```\n\n### Generate Code\n\nAfter you have added your rdl files in the folder, you can use the command below to generate files:\n\n`$ gradle parsec-generate`\n\nHere is an example of the generated folder structure, based on the sample.rdl above:\n\n```\n$ tree build/generated-sources/\nbuild/generated-sources/\n└── java\n    └── your\n        └──group\n            └──name\n                └──parsec_generated\n                    ├── ParsecApplication.java\n                    ├── ParsecErrorBody.java\n                    ├── ParsecErrorDetail.java\n                    ├── ParsecExceptionMapper.java\n                    ├── ParsecResourceError.java\n                    ├── ParsecValidationGroups.java\n                    ├── ParsecWebListener.java\n                    ├── ParsecWrapperServlet.java\n                    ├── ResourceContext.java\n                    ├── ResourceError.java\n                    ├── ResourceException.java\n                    ├── SampleHandler.java\n                    ├── SampleResources.java\n                    ├── SampleServer.java\n                    └── User.java\n\n4 directories, 15 files\n\n$ tree src/main/java/\nsrc/main/java/\n└── your\n    └── group\n        └──name\n            ├── DefaultApplication.java\n            ├── DefaultExceptionMapper.java\n            ├── DefaultResourceContext.java\n            ├── DefaultWebListener.java\n            ├── SampleClient.java\n            ├── SampleClientImpl.java\n            └── SampleHandlerImpl.java\n\n2 directories, 7 files\n```\n\nParsec generated Java server, model code, and Java client for the server. The generated code would include:\n\n+ Java models / data objects, for example: User.java\n+ Jersey resource endpoints, for example: SampleResource.java\n+ Handler interfaces, for example: SampleHandler.java - Handler implementations follow a naming convention: \u003cAPI name\u003eHandlerImpl.java\n+ Java client for your web service, for example: SampleClient.java, SampleClientImpl.java\n\nJava files are generated under ${baseDir}/build/generated-sources/java and the generated Java code are in sub-package \u003cuser defined namespace\u003e.parsec_generated\n\n### Implement Handlers\n\nNow you can start to implement your API by editing *HandlerImpl.java files. Here is an example of SampleHandlerImpl.java:\n\n```\npackage your.group.name;\n\nimport your.group.name.parsec_generated.User;\nimport your.group.name.parsec_generated.SampleHandler;\nimport your.group.name.parsec_generated.ResourceContext;\n\nimport javax.servlet.http.HttpServletRequest;\nimport javax.servlet.http.HttpServletResponse;\n\n/**\n * SampleHandlerImpl is interface implementation that implement SampleHandler interface.\n */\npublic class SampleHandlerImpl implements SampleHandler {\n\n    @Override\n    public User getUsersById(ResourceContext context, Integer id) {\n        User user = new User();\n        user.setName(\"user\");\n        return user;\n    }\n\n    @Override\n    public String postUsers(ResourceContext context, User user) {\n        return \"Post to user \" + user.getName() + \"!\\n\";\n    }\n\n    @Override\n    public String putUsersById(ResourceContext context, Integer id, User user) {\n        return \"put to user \" + user.getName() + \" by id \" + id + \"!\\n\";\n    }\n\n    @Override\n    public ResourceContext newResourceContext(HttpServletRequest request, HttpServletResponse response) {\n        return new DefaultResourceContext(request, response);\n    }\n}\n```\n\n### Start your Server\n\nNow you can start your server with:\n\n`$ gradle jettyRun`\n\nCheck out your [Swagger dashboard](http://localhost:8080/api/static/swagger-ui/)\n\nNow you can run test with:\n\n```\n$ curl http://localhost:8080/api/sample/v1/users/1\n\n{\"age\":0,\"name\":\"user\"}\n\n$ curl -H 'Content-Type: application/json' -d '{\"name\":\"user\",\"age\":10}' http://localhost:8080/api/sample/v1/users\n\nWelcome to Parsec, user!\n```\n\n### Use generated java client\n\nParsec friendly generates a simple client for your web service, including the interface and the implementation.\nClient implementation is base on com.ning.http.client.AsyncHttpClient, you can directly use it or modify it by your needs.\n\nHere is the example of SampleClient.java, which provides methods to the APIs defined in src/main/rdl/sample.rdl.\n\n```\npackage your.group.name;\n\nimport java.util.concurrent.CompletableFuture;\nimport your.group.name.parsec_generated.ResourceException;\nimport your.group.name.parsec_generated.User;\n\n\npublic interface SampleClient {\n    CompletableFuture\u003cUser\u003e getUser(int id) throws ResourceException;\n    CompletableFuture\u003cString\u003e postUser(User user) throws ResourceException;\n    CompletableFuture\u003cString\u003e putUser(int id, User user) throws ResourceException;\n}\n```\n\n## License\n\nCopyright 2016, Yahoo Inc. Copyrights licensed under the Apache 2.0 License. See the accompanying LICENSE file for terms.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyahoo%2Fparsec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyahoo%2Fparsec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyahoo%2Fparsec/lists"}