Hey there, great question!

First, to return empty data you can return Data(), which makes things a little easier.

The data you return should be a response representative of what your API actually returns. For example, if you request a user object from a REST API, you should get back some JSON that represents a user (encoded in Data). In my apps, I'll store this JSON as files and read them from disk when asked to (note: sampleData is not called except when stubbing, so it's not accessed in production).

The reason it's not optional is to force developers to specify something so it's easier to unit test the code that uses Moya. Network call stubs are first-class citizens in Moya, and are as foundational to the library. I understand that not every developer agrees, so return Data() is always going to be an option for developers to opt out of this behaviour. But since all network responses do return some data (even if it's empty) then it doesn't make to make the property optional.

I hope this clarifies things to your satisfaction. We're always looking for ways to improve our documentation, do you have any suggestions where we could add this explanation to help future developers?

After your comment, i tried to read source code of Moya. sampleData will be used as the default EndPoint:

endpointClosure: @escaping EndpointClosure = MoyaProvider.DefaultEndpointMapping

And

Endpoint(URL: url, sampleResponseClosure: {.networkResponse(200, target.sampleData)}, method: target.method, parameters: target.parameters)

I think: sampleData should be cached response as you say: " I'll store this JSON as files and read them from disk when asked to", Why not change the var sampleData: Data to var cachePolicy: Moya.cachePolicy, cache expired date is read from response like that: Cache-Control: max-age=3600, must-revalidate; Expires: Fri, 30 Oct 2016 14:19:41 GMT.

It's simple for developer to use Moya with cache control.

Ah, you're looking to stub requests locally, to return previous requests? Interesting. I'll have to think about that.

Having a plugin to record network calls might be cool, too, especially for testing.

Return cached response when without network. Also as you say. Let's talking about it.

Return previous requests is better, but is that the things Moya should do? I think it's the data-model's job. And we should not confuse the data-model with the service-model. this is my opinion...

I agree with @DeepMissea. This should be it's own library, caching is really hard

Plug for a talk my friend gave: https://www.youtube.com/watch?v=8uqXuEZLyUU
He talks about a caching library called Carlos, I haven't tried it, but he makes a good case for using it https://github.com/WeltN24/Carlos

Caching would be a level above Moya though
You'd probably want to use Carlos from your application level, and Moya (i.e. the network) would be one of the caches you could fetch from.

Nooooo, i recommand use this:

typedef NS_ENUM(NSUInteger, NSURLRequestCachePolicy)
{
    NSURLRequestUseProtocolCachePolicy = 0,
    NSURLRequestReloadIgnoringLocalCacheData = 1,
    NSURLRequestReloadIgnoringLocalAndRemoteCacheData = 4, // Unimplemented
    NSURLRequestReloadIgnoringCacheData = NSURLRequestReloadIgnoringLocalCacheData,
    NSURLRequestReturnCacheDataElseLoad = 2,
    NSURLRequestReturnCacheDataDontLoad = 3,
    NSURLRequestReloadRevalidatingCacheData = 5, // Unimplemented
};

With header fields like Cache-Control: max-age=3600, must-revalidate; Expires: Fri, 30 Oct 2016 14:19:41 GMT, request cache-control is my original opinion.

------Edit-------

I think, request cache-control is useful.

@wilddylan can you elaborate?
Are you saying that you'd like Moya to implement a cache that follows the cache policy you outline?

@wilddylan I'm going to close this for now, please do re-open if you'd like to further explore adding a cache!