RESTful URLs – How to Structure a Set of RESTful URLs

In your latter scheme, you keep verbs in the URLs of your resources. This should be avoided as the HTTP verbs should be used for that purpose. Embrace the underlying protocol instead of ignoring, duplicating or overriding it.

Just look at DELETE /item/delete/:id, you place the same information twice in the same request. This is superfluous and should be avoided. Personally, I'd be confused with this. Does the API actually support DELETE requests? What if I place delete in the URL and use a different HTTP verb instead? Will it match anything? If so, which one will be chosen? As a client of a properly designed API, I shouldn't have to ask such questions.

Maybe you need it to somehow support clients that cannot issue DELETE or PUT requests. If that's the case, I'd pass this information in an HTTP header. Some APIs use an X-HTTP-Method-Override header for this specific purpose (which I think is quite ugly anyway). I certainly wouldn't place the verbs in the paths though.

Go for

GET     /items      # Read all items
GET     /items/:id  # Read one item
POST    /items      # Create a new item
PUT     /items/:id  # Update one item
DELETE  /items/:id  # Delete one item

What's important about the verbs is that they are already well-defined in the HTTP specification and staying in line with these rules allows you to use caches, proxies and possibly other tools external to your application that understand the semantics of HTTP but not your application semantics. Please note that the reason you should avoid having them in your URLs is not about RESTful APIs requiring readable URLs. It's about avoiding unnecessary ambiguity.

What's more, a RESTful API can map these verbs (or any subset thereof) to any set of application semantics, as long as it doesn't go against the HTTP specification. For example, it is perfectly possible to build a RESTful API that only uses GET requests if all operations that it allows are both safe and idempotent. The above mapping is just an example that fits your use case and is compliant with the spec. It doesn't necessarily have to be like this.

Please also mind that a truly RESTful API should never require a programmer to read extensive documentation of available URLs as long as you conform to the HATEOAS (Hypertext as the Engine of Application State) principle, which is one of the core assumptions of REST. The links can be utterly incomprehensible to humans as long as the client application can understand and use them to figure out possible application state transitions.

Here is one of my favorite kick-off examples of structure for your spring rest app.

1. Separation of layers, each layer is an individual module/project

• REST API
  • Packaged as war (Could be jar if you are using spring boot with embedded server. Spring boot doc clearly explains how to deploy the so-call uber jar. It is deadly simple.)
  • It has rest controllers that handle request/responses
  • depends on Service Module below
• Service
  • Packaged as jar
  • Business logic abstractions, this layer has no idea how to communicate with datasource.
  • It will be autowired in rest controllers
  • Depends on DAO/Repository module below
• DAO/Repository
  • Packaged as jar
  • Talks to data source directly, has operations commonly known as CRUD. It could be simple jdbc, JPA, or even file access.
  • Depends on domain module below
• Domain
  • Packaged as jar
  • It has your domain models, normally POJO classes. If you are using ORM, they are ORM entities.
  • It could also have DTO (Data Transfer Object), which are still under hot debates. Use it or not is your call.
• You can add more modules such as utility, third party integration, etc.. but the above are highly recommended to have.

2. Build/Dependency Management Tools (Very necessary IMHO)

There are plenty of them, google search will show you. I personally like Maven with Spring. It simply works for the above project structure.
Also note that if you are using maven, there is a parent module that aggregates all the modules discussed in section 1. All the bullet point modules also corresponds to maven modules.

3. Thoughts on your particular project

Since you are using REST, I would highly recommend that you NOT use JSP as your view. You can use plain HTML5 + Javascript or some popular framework like AngularJS as your view.
If you insist on using JSP, you will need introduce another war(web app) that has controllers and JSPs. Controller will get the data(Normally Json/xml format) and then parse them to your models(POJO) so that your JSP can get them from your controller and do the display. Posting data from JSP is the reverse, I omitted here.

It is nowhere near a complete guide since this topic is quite huge and depends heavily on your specific requirement but the terms included here is enough for you to do additional research(Google, it is). Hopefully this will give you some ideas on how to approach.