{"id":25441955,"url":"https://github.com/mieskeb/json-api-spring-boot","last_synced_at":"2025-11-01T14:30:21.815Z","repository":{"id":43011702,"uuid":"293347088","full_name":"MieskeB/json-api-spring-boot","owner":"MieskeB","description":"This project converts a normal Java object to json:api standard. More information about json:api can be found here: https://jsonapi.org/. Created and maintained by Mindware Software.","archived":false,"fork":false,"pushed_at":"2023-05-26T15:29:39.000Z","size":137,"stargazers_count":10,"open_issues_count":2,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-17T13:16:06.839Z","etag":null,"topics":["java","json-api","spring-boot"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MieskeB.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":"CODEOWNERS","security":null,"support":null}},"created_at":"2020-09-06T19:23:30.000Z","updated_at":"2024-06-04T09:18:38.000Z","dependencies_parsed_at":"2022-08-24T14:35:41.696Z","dependency_job_id":null,"html_url":"https://github.com/MieskeB/json-api-spring-boot","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MieskeB%2Fjson-api-spring-boot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MieskeB%2Fjson-api-spring-boot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MieskeB%2Fjson-api-spring-boot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MieskeB%2Fjson-api-spring-boot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MieskeB","download_url":"https://codeload.github.com/MieskeB/json-api-spring-boot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239293947,"owners_count":19615043,"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":["java","json-api","spring-boot"],"created_at":"2025-02-17T13:16:09.936Z","updated_at":"2025-11-01T14:30:21.764Z","avatar_url":"https://github.com/MieskeB.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Maven Central](https://maven-badges.herokuapp.com/maven-central/nl.michelbijnen.jsonapi/json-api/badge.svg)](https://maven-badges.herokuapp.com/maven-central/nl.michelbijnen.jsonapi/json-api)\n[![Coverage Status](https://coveralls.io/repos/github/MieskeB/json-api-spring-boot/badge.svg?branch=master)](https://coveralls.io/github/MieskeB/json-api-spring-boot?branch=master)\n\n# json-api-spring-boot\n\nThis project converts a normal Java object to json:api standard. More information about json:api can be found\nhere: https://jsonapi.org/\n\n# Installation\n\nFor maven, add the following dependency to your dependencies:\n\n```xml\n\n\u003cdependency\u003e\n    \u003cgroupId\u003enl.michelbijnen.jsonapi\u003c/groupId\u003e\n    \u003cartifactId\u003ejson-api\u003c/artifactId\u003e\n    \u003cversion\u003e1.5.6\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nDo the same if you are using gradle:\n\n```\nimplementation 'nl.michelbijnen.jsonapi:json-api:1.5.6'\n```\n\n(Don't forget to (re)import all your dependencies afterwards)\n\n# Conflicts\n\nWe are aware this library has conflicts with spring-boot-starter-test. This is due to a dependency in that library\ncalled android-json. This can be solved by changing the dependency to the following:\n\n```xml\n\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.springframework.boot\u003c/groupId\u003e\n    \u003cartifactId\u003espring-boot-starter-test\u003c/artifactId\u003e\n    \u003cscope\u003etest\u003c/scope\u003e\n    \u003cexclusions\u003e\n        \u003cexclusion\u003e\n            \u003cgroupId\u003ecom.vaadin.external.google\u003c/groupId\u003e\n            \u003cartifactId\u003eandroid-json\u003c/artifactId\u003e\n        \u003c/exclusion\u003e\n    \u003c/exclusions\u003e\n\u003c/dependency\u003e\n```\n\n# Usage\n\n## Setting up\n\nTo start, you'll need a project. In this project, you have to define models. These models (with properties) need the\ndefault getters and setters according to the Java standards.\n\nAn example for this:\n\n```java\npublic class User {\n    private String id;\n    private String username;\n\n    public String getId() {\n        return id;\n    }\n\n    public void setId(String id) {\n        this.id = id;\n    }\n\n    public String getUsername() {\n        return username;\n    }\n\n    public void setUsername(String username) {\n        this.username = username;\n    }\n}\n```\n\nNaming in this step is very important! So if possible, let them be generated by your editor (IntelliJ can do this\nusing `alt`+`ins` and then clicking on getter and setter) or by letting Lombok handle it (put @Getter and @Setter above\nthe class)\n\n## Adding annotations\n\nFor links to be generated correctly, a class needs to be extended. This class will help generate the links and makes\nsure that the id is included into the object.\n\n```java\nimport nl.michelbijnen.jsonapi.generator.JsonApiDtoExtendable;\n\npublic class User extends JsonApiDtoExtendable {\n    // ...\n}\n```\n\nBy adding this class, you can remove id and all links.\n\nThere is a list of annotations that can be added.\n\n| Annotation       | Description                   | Mandatory | Covered by JsonApiDtoExtendable |\n| ---------------- | ----------------------------- | --------- | -------------------- |\n| @JsonApiObject   | The whole object              | Yes       | No                   |\n| @JsonApiId       | The id of the object          | Yes       | Yes                  |\n| @JsonApiProperty | The properties of the object  | No        | No                   |\n| @JsonApiLink     | The link with references      | No        | Yes                  |\n| @JsonApiRelation | A relation with another class | No        | No                   |\n\nNow to implement the example class above with the annotations:\n\n```java\nimport nl.michelbijnen.jsonapi.annotation.*;\nimport nl.michelbijnen.jsonapi.generator.JsonApiDtoExtendable;\n\n@JsonApiObject(\"User\")\npublic class User extends JsonApiDtoExtendable {\n    @JsonApiProperty\n    private String username;\n\n    public String getUsername() {\n        return username;\n    }\n\n    public void setUsername(String username) {\n        this.username = username;\n    }\n}\n```\n\n### Adding relations\n\nJSON:API says that you can add a relation to another class, but only the ID will appear. In the includes, the whole\nobject can be found. To do this, add a field with `@JsonApiRelation`. A value is mandatory.\n\n```java\n@JsonApiRelation(\"owner\")\nprivate Box boxOwner;\n```\n\nThis box object should also have the `@JsonApiObject(\"box\")` annotation, and it should also contain an id.\n\nMany to many relations are supported and won't cause any recursions.\n\n### Adding links\n\nAfter filling in all the fields, a generate method can be called. This method will require you to input the self URI and\nthe all URI. After that it will automatically generate all URLs required for that object. For generation, the library\nneeds to know the base URL. Default for spring boot is `http://localhost:8080` and this is also the default value for\nthis URL.\n\nif you want to change the default value, you can set an environment variable (or put this in your\nserver.properties): `jsonapi.baseurl=http://localhost:8081`\n\n```java\nimport nl.michelbijnen.jsonapi.annotation.*;\nimport nl.michelbijnen.jsonapi.generator.JsonApiDtoExtendable;\n\n@JsonApiObject(\"User\")\npublic class User extends JsonApiDtoExtendable {\n    @JsonApiProperty\n    private String username;\n\n    public User(String id, String username) {\n        this.setId(id);\n        this.setUsername(username);\n        this.generate(\"/user\", \"/users\");\n    }\n\n    public String getUsername() {\n        return username;\n    }\n\n    public void setUsername(String username) {\n        this.username = username;\n    }\n}\n```\n\nIf you would create the json for this object, you would get the following results:\n\nAs a single object:\n\n```json\n{\n  \"data\": {\n    \"attributes\": {\n      \"username\": \"the username\"\n    },\n    \"id\": \"the id\",\n    \"type\": \"User\"\n  },\n  \"links\": {\n    \"self\": \"http://localhost:8080/user/the+id\"\n  }\n}\n```\n\nAs a list:\n\n```json\n{\n  \"data\": [\n    {\n      \"attributes\": {\n        \"username\": \"the username 1\"\n      },\n      \"id\": \"the id 1\",\n      \"type\": \"User\"\n    },\n    {\n      \"attributes\": {\n        \"name\": \"the username 2\"\n      },\n      \"id\": \"the id 2\",\n      \"type\": \"User\"\n    }\n  ],\n  \"links\": {\n    \"self\": \"http://localhost:8080/users\"\n  }\n}\n```\n\n## Creating the string\n\nNow to convert the object to a string, you can do that the following way with a full user object.\n\n```java\nimport nl.michelbijnen.jsonapi.parser.JsonApiConverter;\n\nString result=JsonApiConverter.convert(user);\n```\n\n## Adding depth to the included\n\nDefault, there is a depth of 1. This means that the included will go 1 relation deep. So only the direct relations of\nthe base object. If you want to have the relations of the relations, you can change this to 2 or higher for more depth.\n\n```java\nimport nl.michelbijnen.jsonapi.parser.JsonApiConverter;\n\nString result=JsonApiConverter.convert(user,2);\n```\n\nif you want to change the default value, you can set an environment variable (or put this in your\nserver.properties): `jsonapi.depth=2`\n\n# Conclusion\n\nI hope this helps some people who had trouble with using JSON:API. If there are any problems or bugs, just create an\nissue with what is wrong! I'm happy to help! Also if someone wants to clean up some code or make it more efficient, you\ncan always open a pull request!\n\nOther (full) examples can be found in `src/main/java/nl/michelbijnen/jsonapi/test`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmieskeb%2Fjson-api-spring-boot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmieskeb%2Fjson-api-spring-boot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmieskeb%2Fjson-api-spring-boot/lists"}