You can find all the documentation for the ServiceStack Web Framework on the wiki
ServiceStack's new API was just released this week which already contain the answers to all your questions. I would go back and read them in-full but I'll extract the snippets that answers your questions:
Is there a documentation that actually says which interfaces/base classes to use, and what do they do?
Under the Introducing the New API section is:
The new API design simplifies the existing IService and IRestService with this single unified interface:
public interface IService {}
That is now able to handle both RPC Service and Rest Service requests in a single class. The interface is just used as a Marker interface that ServiceStack uses to find, register and auto-wire your existing services. A convenience concrete Service class is also included which contains easy access to ServiceStack's providers
A new API design shows an example of DTO implementing IReturn interface, and service inheriting from Service - but there's no explanation if this is the preferred way now
The heading at the top of the wiki reads:
Recommended for future Web Service Development
As the new API Design offers many benefits over the existing API, we're recommending its use for any new web service development. It will take us some time, but we intend to port all the old examples to adopt the new API ourselves. One reason to still prefer the older API is if you also wanted to support SOAP clients and endpoints which still requires the strict-ness enforced by the previous approach.
Under the Inspiration heading reads:
The beauty of this proposal was that it already fitted perfectly with ServiceStack's existing message-based semantics which meant we were able to implement it in record time without any disruption or breaking changes to the existing code-base. The result is that you can now start creating new services along side your existing services and they'll both continue to work seamlessly side-by-side.
is it required to implement IReturn
Under the heading Calling Services from a Typed C# Client is:
lets say you take the normal route of copying the DTOs (in either source of binary form) so you have something like this on the client:
[Route("/reqstars")]
public class AllReqstars : IReturn<List<Reqstar>> { }
The code on the client now just becomes:
var client = new JsonServiceClient(BaseUri);
List<Reqstar> response = client.Get(new AllReqstars());
Which makes a GET web request to the /reqstars route. When a custom route is not present on the client it automatically falls back to using ServiceStack's pre-defined routes.
Finally you can also use the previous more explicit client API (ideal for when you don't have the IReturn<> marker):
var response = client.Get<List<Reqstar>>("/reqstars");
All these APIs have async equivalents which you can use instead, when you need to.
how to deal with POST/GET/etc,
The entire API docs is effectively about explaining how Post's Get's work. You have a client.Get() on the client which calls the Get() on the server, or falls back to using Any() if it doesn't exist.
The bottom of the Wiki page goes through how to manually port your services from an older API to the newer one.
And here are some examples using the new API:
