Working with endpoints

Endpoints define the server methods that the client can call. With Serverpod, you add methods to your endpoint, and your client code will be generated to make the method call.

For the client code to be generated:

• Place the endpoint file anywhere under the lib directory of your server.
• Create a class that extends Endpoint.
• Define methods that return a typed Future and take a Session object as their first argument.

The Session object holds information about the call being made and provides access to the database.

Creating an endpoint

import 'package:serverpod/serverpod.dart';

class ExampleEndpoint extends Endpoint {
  Future<String> hello(Session session, String name) async {
    return 'Hello $name';
  }
}

The above code will create an endpoint called example (the Endpoint suffix will be removed) with the single hello method. To generate the client-side code run serverpod generate in the home directory of the server.

info

You can pass the --watch flag to serverpod generate to watch for changed files and generate code whenever your source files are updated. This is useful during the development of your server.

Calling an endpoint

On the client side, you can now call the method by calling:

var result = await client.example.hello('World');

The client is initialized like this:

// Sets up a singleton client object that can be used to talk to the server from
// anywhere in our app. The client is generated from your server code.
// The client is set up to connect to a Serverpod running on a local server on
// the default port. You will need to modify this to connect to staging or
// production servers.
var client = Client('http://$localhost:8080/')
  ..connectivityMonitor = FlutterConnectivityMonitor();

If you run the app in an Android emulator, the localhost parameter points to 10.0.2.2, rather than 127.0.0.1 as this is the IP address of the host machine. To access the server from a different device on the same network (such as a physical phone) replace localhost with the local ip address. You can find the local ip by running ifconfig (Linux/MacOS) or ipconfig (Windows).

Make sure to also update the publicHost in the development config to make sure the server always serves the client with the correct path to assets etc.

# your_project_server/config/development.yaml

apiServer:
  port: 8080
  publicHost: localhost # Change this line
  publicPort: 8080
  publicScheme: http

Passing parameters

There are some limitations to how endpoint methods can be implemented. Parameters and return types can be of type bool, int, double, String, UuidValue, Duration, DateTime, ByteData, Uri, BigInt, or generated serializable objects (see next section). A typed Future should always be returned. Null safety is supported. When passing a DateTime it is always converted to UTC.

You can also pass List, Map, Record, and Set as parameters, but they need to be strictly typed with one of the types mentioned above.

warning

While it's possible to pass binary data through a method call and ByteData, it is not the most efficient way to transfer large files. See our file upload interface. The size of a call is by default limited to 512 kB. It's possible to change by adding the maxRequestSize to your config files. E.g., this will double the request size to 1 MB:

maxRequestSize: 1048576

Return types

The return type must be a typed Future. Supported return types are the same as for parameters.

Excluding endpoints from code generation

If you want the code generator to ignore an endpoint definition, you can annotate either the entire class or individual methods with @doNotGenerate. This can be useful if you want to keep the definition in your codebase without generating server or client bindings for it.

Exclude an entire Endpoint class

Annotate the class with @doNotGenerate to exclude it entirely:

import 'package:serverpod/serverpod.dart';

@doNotGenerate
class ExampleEndpoint extends Endpoint {
  Future<String> hello(Session session, String name) async {
    return 'Hello $name';
  }
}

The above code will not generate any server or client bindings for the example endpoint.

Exclude individual Endpoint methods

Alternatively, you can exclude individual methods by annotating them with @doNotGenerate.

import 'package:serverpod/serverpod.dart';

class ExampleEndpoint extends Endpoint {
  Future<String> hello(Session session, String name) async {
    return 'Hello $name';
  }

  @doNotGenerate
  Future<String> goodbye(Session session, String name) async {
    return 'Bye $name';
  }
}

In this case the ExampleEndpoint will only expose the hello method, whereas the goodbye method will not be accessible externally.