ServiceStack - is there an up-to date, complete do

I'm trying to wrap my head around ServiceStack, and while it claims that it has really good documentation, it doesn't seem to be the case so far. Is there a documentation that actually says which interfaces/base classes to use, and what do they do ?

Just.. have a bunch of quesitons, and can find very few answers.. 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, is it required to implement IReturn, how to deal with POST/GET/etc, etc, etc..

Any links would be appreciated.

And yes, I have samples, but for example they don't have anything on this IReturn interface.. and samples won't beat the documentation anyways.

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: