Panache REST guide #9254

gytis · 2020-05-13T09:40:59Z

gytis · 2020-05-13T09:42:21Z

docs/src/main/asciidoc/panache-rest.adoc

+
+== Resource customisation
+
+Panache REST provides a `@PanacheRestResource` annotation that can be used to customize certain features of the resource.


It's out of scope for this PR but I'm not happy with a name of this annotation (@PanacheRestResource). It's very similar to the interface name (PanacheCrud..Resource) and might be confusing. Any suggestions on the name change @geoand?

I dunno.... I'm probably the worst developer when it comes to naming...

geoand

Nice start!

Added some comments

docs/src/main/asciidoc/panache-rest.adoc

gsmet

I added some comments, some are related to the implementation itself rather than the doc.

/cc @geoand for further discussions.

gsmet · 2020-05-13T12:04:49Z

docs/src/main/asciidoc/panache-rest.adoc

+and pull requests should be submitted there:
+https://github.com/quarkusio/quarkus/tree/master/docs/src/main/asciidoc
+////
+


Please avoid the newline here, the website is very picky about that.

docs/src/main/asciidoc/panache-rest.adoc

gsmet · 2020-05-13T12:08:03Z

docs/src/main/asciidoc/panache-rest.adoc

+
+[source,java]
+----
+@Path("/entities") // Base bath is a pluralised name of an entity


I think this is a mistake. We shouldn't "pluralize" things as there's a good chance we will get some of them wrong and it really doesn't bring anything.

Keep in mind that a lot of people code in their own languages where the plural rules will be completely different.

Also, frankly, I don't think it's better as a plural so why take the risk?

/cc @FroMage

If we want plural, perhaps let the user specify it?

Just to give an example, in French, we have a lot of specific plural forms (cheval -> chevaux for instance).

Yeah, taking the entity name as is would be the default and you could define a specific path in the annotation?

Just an FIY Spring Data REST simply adds s to every entity name.

Oh, my. OK I will create an issue.

Makes it even more fun with:

@Entity public class 馬 extends PanacheEntity { }

And the URI ends up being /馬s, right? :)

Myself, I've always used Cheval for the entity name (singular) and Chevaux (plural) for the controller name. And RoR derives the URIs from the controller names, so it would be /chevaux correctly.

I just suggest we advertise the same convention, it solves many issues. And we default to the controller name for the URI, instead of the entity name.

Naturally we should also allow users to override it.

And the URI ends up being /馬s, right? :)

I would think so. At least for a simple people I got a path /peoples when i tried it last time.

I just suggest we advertise the same convention, it solves many issues. And we default to the controller name for the URI, instead of the entity name.

Extracting a name from a controller will be trickier because a user can name his classes differently. We could recommend a convention but who knows if they'll follow it.
With an entity we could simply take an its name, make it all lowercase separated with - instead of camelcase and get on with it. And then I'll add an option to override the path.

Extracting a name from a controller will be trickier because a user can name his classes differently. We could recommend a convention but who knows if they'll follow it.

The point of conventions is that people follow them. If they don't they can't customise the output.

Entities are already singular by convention. Controller names don't have a convention other than the brain-dead "resource" that jax-rs got confused about.

It's pretty easy to tell people to name their controller People and default to using that name.

Let's discuss it on #9261 since the guide change won't be enough for this anyway.

gsmet · 2020-05-13T12:11:29Z

docs/src/main/asciidoc/panache-rest.adoc

+
+=== Available options
+
+* `hal` - in addition to the standard `application/json` responses, generates additional methods that can return `application/hal+json` responses if requested via `Accept` header.


Wondering if we should have an array of content types instead with the default being { "application/json" }. That would be much more flexible.

/cc @FroMage

Well, I don't think we currently support any response type, but this seems like a valid point for the future.

application/json is hardcoded and application/hal+json can be enabled as an extra. Because HAL is a complex format I had to implement a custom serialiser for it which serialisers special wrapper objects.

OK, let's keep it that way for now.

gytis · 2020-05-13T14:15:18Z

I think I've addresses all the comments except the one about plural paths. For that I'll make a separate guide modification once I change the extension code.

FroMage

Great guide. Please don't hate me for reconsidering naming before it's too late…

docs/src/main/asciidoc/panache-rest.adoc

FroMage · 2020-05-13T14:28:05Z

docs/src/main/asciidoc/panache-rest.adoc

+To begin with:
+
+* Add the required dependencies to your `pom.xml`
+** Panache REST with Hiberante ORM extension (`quarkus-panache-rest-hibernate-orm`)


Now that I read it like that, I've my doubts over the order, because originally it was supposed to be X with Panache, which means X with style.

This makes it looks like Panache is a noun and the subject instead of an adjective to make Hibernate ORM/REST stylish.

Perhaps it should be Hibernate ORM REST with Panache or RESTful Hibernate ORM with Panache or REST for Hibernate ORM with Panache?

I guess, similarly, this guide (and the extension names) would better be "REST with Panache" and rest-panache?

Except this sort-of implies it applies to REST apps that aren't necessarily about data, and we plan to have a Panache layer for RESTEasy one day…

Perhaps RESTful data with Panache?

Or CRUD with Panache?

In any case, we need to make the extension name consistent with the naming rules we define here.

Should I create a separate issue to agree on the name there?

We can, yes, but this will heavily impact this guide.

I could just update the guide together with the code once we agree on a name.

gytis · 2020-05-18T11:02:46Z

I've updated the guide to align with the changes from #9373 but I'll need to rebase after the merge. There will be a conflict in a quarkus-extension.yaml file because of a module rename.

geoand · 2020-05-18T11:04:58Z

We'll need a review from @FroMage for this one :)

gytis · 2020-05-19T09:26:12Z

Closing this PR because I've cherry-picked the commit to #9373

boring-cyborg bot added area/documentation area/panache labels May 13, 2020

gytis commented May 13, 2020

View reviewed changes

geoand reviewed May 13, 2020

View reviewed changes

gytis force-pushed the panache-rest-guide branch from 2ed482f to 7adaa2a Compare May 13, 2020 11:58

geoand reviewed May 13, 2020

View reviewed changes

docs/src/main/asciidoc/panache-rest.adoc Show resolved Hide resolved

gsmet requested changes May 13, 2020

View reviewed changes

gsmet mentioned this pull request May 13, 2020

Don't pluralize paths in Panache Rest #9261

Closed

gytis force-pushed the panache-rest-guide branch from 60061aa to 3db4542 Compare May 13, 2020 14:10

FroMage requested changes May 13, 2020

View reviewed changes

gytis mentioned this pull request May 14, 2020

Naming Panache REST extension #9293

Closed

gytis marked this pull request as draft May 15, 2020 14:07

snowdrop-bot mentioned this pull request May 18, 2020

dev_21 snowdrop/team#46

Closed

gytis force-pushed the panache-rest-guide branch from 9cfdd36 to 2586a3d Compare May 18, 2020 10:59

REST data with Panache guide

8eef976

gytis force-pushed the panache-rest-guide branch from 2586a3d to 8eef976 Compare May 18, 2020 16:44

gytis mentioned this pull request May 18, 2020

REST data Panache reorganisation #9373

Merged

gytis closed this May 19, 2020

gsmet added the triage/invalid This doesn't seem right label May 20, 2020

gytis deleted the panache-rest-guide branch May 26, 2020 09:51


		== Resource customisation

		Panache REST provides a `@PanacheRestResource` annotation that can be used to customize certain features of the resource.


		=== Available options

		* `hal` - in addition to the standard `application/json` responses, generates additional methods that can return `application/hal+json` responses if requested via `Accept` header.

Panache REST guide #9254

Panache REST guide #9254

Uh oh!

Conversation

gytis commented May 13, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

geoand left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gsmet left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gytis commented May 13, 2020

Uh oh!

FroMage left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment