Endpoints
Every endpoint lives in src/Presentation/Endpoints, one static class per feature. Requests and responses are JSON with camelCase property names, read case-insensitively. Properties with no value are left out of responses. In a solution created with --include-auth, every endpoint except health needs a token (see Secure the API).
The OpenAPI document at /openapi/v1.json describes all of this too, and Scalar at /scalar lets you call it. The examples use the dotnet run address, https://localhost:7311; with Docker Compose it’s http://localhost:7310.
| Method | Route | Returns |
|---|---|---|
GET |
/api/movies |
A page of movie summaries |
GET |
/api/movies/{id} |
A movie with its reviews |
GET |
/api/authors |
A page of author summaries |
GET |
/api/authors/{id} |
An author with their reviews |
GET |
/api/reviews |
A page of reviews |
GET |
/api/reviews/{id} |
A review |
POST |
/api/reviews |
The created review, with a Location header |
PUT |
/api/reviews/{id} |
Nothing, 204 No Content |
DELETE |
/api/reviews/{id} |
Nothing, 204 No Content |
GET |
/api/version |
The version |
Movies
Section titled “Movies”GET /api/movies
Section titled “GET /api/movies”Lists movies ordered by title, one page at a time, optionally only those whose title contains a search term.
| Query parameter | Type | Default | Rules |
|---|---|---|---|
query |
string | none | Up to 100 characters. Matches the title, ignoring case |
offset |
integer | 0 |
0 or more |
limit |
integer | 10 |
1 to 50 |
curl "https://localhost:7311/api/movies?query=space&limit=2"{ "items": [ { "id": "cb188ef6-14e7-f85f-2f78-924c2ab26b28", "title": "Deep Space Gardeners", "reviewCount": 5, "averageStars": 3.4 }, { "id": "dfefa450-5454-6a4d-a4aa-95a9b047c17b", "title": "Postcards from Outer Space", "reviewCount": 1, "averageStars": 3 } ], "offset": 0, "limit": 2, "totalCount": 4}GET /api/movies/{id}
Section titled “GET /api/movies/{id}”Returns one movie with every review written about it, or 404 when there’s no movie with that id.
Authors
Section titled “Authors”GET /api/authors
Section titled “GET /api/authors”Lists authors ordered by last name then first name, one page at a time, optionally only those whose name contains a search term. Takes the same parameters as GET /api/movies. query matches anywhere in the full name, written first name then last name.
{ "items": [ { "id": "01fa8b58-05d2-abd4-e55c-2633222dd0a5", "firstName": "Jana", "lastName": "Auer", "reviewCount": 9, "averageStars": 3.3 }, { "id": "1cc2ad51-61c5-63ee-dd6e-15308cfe6e51", "firstName": "Caroline", "lastName": "Bins", "reviewCount": 10, "averageStars": 3.2 } ], "offset": 0, "limit": 2, "totalCount": 15}GET /api/authors/{id}
Section titled “GET /api/authors/{id}”Returns one author with every review they have written, or 404 when there’s no author with that id.
Reviews
Section titled “Reviews”GET /api/reviews
Section titled “GET /api/reviews”Lists reviews ordered by movie then author, one page at a time. Filter by movie, by author, by words in the review text and by a minimum star rating, in any combination.
| Query parameter | Type | Default | Rules |
|---|---|---|---|
movieId |
guid | none | Only reviews of this movie |
authorId |
guid | none | Only reviews by this author |
query |
string | none | Up to 100 characters. Matches the review text, ignoring case |
minStars |
integer | none | 1 to 5. Only reviews with at least this many stars |
offset |
integer | 0 |
0 or more |
limit |
integer | 10 |
1 to 50 |
curl "https://localhost:7311/api/reviews?movieId=cb188ef6-14e7-f85f-2f78-924c2ab26b28&limit=2"{ "items": [ { "id": "45911e6f-a366-417b-1453-f34097338ee2", "stars": 5, "reviewedMovie": { "id": "cb188ef6-14e7-f85f-2f78-924c2ab26b28", "title": "Deep Space Gardeners" }, "reviewAuthor": { "id": "1cc2ad51-61c5-63ee-dd6e-15308cfe6e51", "firstName": "Caroline", "lastName": "Bins" }, "text": "Everyone involved should be very proud." }, { "id": "8832846c-4100-e92a-0b66-e59dcfde2acc", "stars": 3, "reviewedMovie": { "id": "cb188ef6-14e7-f85f-2f78-924c2ab26b28", "title": "Deep Space Gardeners" }, "reviewAuthor": { "id": "1cc2ad51-61c5-63ee-dd6e-15308cfe6e51", "firstName": "Caroline", "lastName": "Bins" }, "text": "I laughed twice and looked at my phone once." } ], "offset": 0, "limit": 2, "totalCount": 5}curl "https://localhost:7311/api/reviews?query=funny&minStars=4&limit=2"{ "items": [ { "id": "85196da9-b404-4905-a1f8-9e0dc88f67e4", "stars": 5, "reviewedMovie": { "id": "33b07882-f520-65ee-5997-b1024edd80b5", "title": "A Quiet Murder in Wagga Wagga" }, "reviewAuthor": { "id": "cb188ef6-14e7-f85f-2f78-924c2ab26b28", "firstName": "Martha", "lastName": "Nicolas" }, "text": "Funny, sad and completely gripping." }, { "id": "625d83d4-587f-f872-f5b5-7f923a37856f", "stars": 4, "reviewedMovie": { "id": "ac6e5917-e549-db65-a0b7-aff1fc817570", "title": "Dragon of the Salt Flats" }, "reviewAuthor": { "id": "cb188ef6-14e7-f85f-2f78-924c2ab26b28", "firstName": "Martha", "lastName": "Nicolas" }, "text": "Funny, warm and better than it needed to be." } ], "offset": 0, "limit": 2, "totalCount": 6}GET /api/reviews/{id}
Section titled “GET /api/reviews/{id}”Returns one review, or 404 when there’s no review with that id.
POST /api/reviews
Section titled “POST /api/reviews”Creates a review. The author and the movie must already exist.
| Body property | Type | Rules |
|---|---|---|
authorId |
guid | Required. An existing author |
movieId |
guid | Required. An existing movie |
stars |
integer | 1 to 5 |
text |
string | Optional. Up to 1000 characters |
curl -X POST "https://localhost:7311/api/reviews" -H "Content-Type: application/json" \ -d '{"authorId":"01fa8b58-05d2-abd4-e55c-2633222dd0a5","movieId":"cb188ef6-14e7-f85f-2f78-924c2ab26b28","stars":5,"text":"Great film. I cried at the ending."}'Answers 201 Created with the new review in the body and its URL in the Location header. An unknown author or movie answers 404.
PUT /api/reviews/{id}
Section titled “PUT /api/reviews/{id}”Changes the star rating of a review, and its text when there’s new text. The author and the movie of a review can’t change.
| Body property | Type | Rules |
|---|---|---|
stars |
integer | 1 to 5 |
text |
string | Optional. Up to 1000 characters. Leave it out to keep the text the review has |
Answers 204 No Content, or 404 when there’s no review with that id.
DELETE /api/reviews/{id}
Section titled “DELETE /api/reviews/{id}”Permanently removes a review. Answers 204 No Content, or 404 when there’s no review with that id.
Version
Section titled “Version”GET /api/version
Section titled “GET /api/version”Returns the version stamped into the build. With --include-auth it needs a token, like everything else; the version is also on every span, metric and log as service.version.
{ "fileVersion": "1.1.0.0", "informationalVersion": "1.1.0.0+044d2922e197f24d9a3f311f87a7e323add1a530" }Every list endpoint returns one page.
| Property | Type | Description |
|---|---|---|
items |
array | The results on this page |
offset |
integer | The offset that was asked for |
limit |
integer | The limit that was asked for |
totalCount |
integer | The number of results across every page |
To read everything, start at offset 0 and add limit to it until offset reaches totalCount.
MovieSummary
Section titled “MovieSummary”| Property | Type | Description |
|---|---|---|
id |
guid | The movie’s id |
title |
string | The movie’s title |
reviewCount |
integer | How many reviews the movie has |
averageStars |
number | The average rating to one decimal place. Left out when there are no reviews |
| Property | Type | Description |
|---|---|---|
id |
guid | The movie’s id |
title |
string | The movie’s title |
reviews |
array of review | Every review of the movie |
AuthorSummary
Section titled “AuthorSummary”| Property | Type | Description |
|---|---|---|
id |
guid | The author’s id |
firstName |
string | The author’s first name |
lastName |
string | The author’s last name |
reviewCount |
integer | How many reviews the author has written |
averageStars |
number | The average rating they give. Left out when there are no reviews |
Author
Section titled “Author”| Property | Type | Description |
|---|---|---|
id |
guid | The author’s id |
firstName |
string | The author’s first name |
lastName |
string | The author’s last name |
reviews |
array of review | Every review by the author |
Review
Section titled “Review”| Property | Type | Description |
|---|---|---|
id |
guid | The review’s id |
stars |
integer | The rating, from 1 to 5 |
reviewedMovie |
object | The movie’s id and title |
reviewAuthor |
object | The author’s id, firstName and lastName |
text |
string | What the author said about the movie. Left out when there’s no text |
Version
Section titled “Version”| Property | Type | Description |
|---|---|---|
fileVersion |
string | The assembly file version |
informationalVersion |
string | The informational version, with the prerelease label and commit hash when there are any |
Errors
Section titled “Errors”Every error is a Problem Details response with the application/problem+json content type.
| Status | When | Extra properties |
|---|---|---|
400 Bad Request |
A parameter or body property breaks one of the rules above, or the body isn’t valid JSON | errors, a property name to messages map, for validation failures |
401 Unauthorized |
Authentication is on and the token is missing or not valid | |
404 Not Found |
The movie, author or review doesn’t exist | detail says which |
500 Internal Server Error |
Something unexpected happened |
{ "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "Limit": ["A limit must be between 1 and 50."] }, "traceId": "00-4241b018629bd38a0a6d370c3a214e2f-cce80e4f478496c2-00"}{ "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5", "title": "Not Found", "status": 404, "detail": "The Movie with the supplied id was not found.", "traceId": "00-85575ee9ac241f705f634081d3bb7fba-93e062125f418354-00"}