|
| 1 | +# Step-By-Step Guide to a Running API |
| 2 | + |
| 3 | +The most basic use case leverages Entity Framework. |
| 4 | +The shortest path to a running API looks like: |
| 5 | + |
| 6 | +- Create a new web app |
| 7 | +- Install |
| 8 | +- Define models |
| 9 | +- Define the DbContext |
| 10 | +- Define controllers |
| 11 | +- Add Middleware and Services |
| 12 | +- Seed the database |
| 13 | +- Run Migrations |
| 14 | +- Start the app |
| 15 | + |
| 16 | +This page will walk you through the **simplest** use case. More detailed examples can be found in the detailed usage subsections. |
| 17 | + |
| 18 | +### Create A New Web App |
| 19 | + |
| 20 | +``` |
| 21 | +mkdir MyApp |
| 22 | +cd MyApp |
| 23 | +dotnet new webapi |
| 24 | +``` |
| 25 | + |
| 26 | +### Install |
| 27 | + |
| 28 | +``` |
| 29 | +dotnet add package JsonApiDotnetCore |
| 30 | +
|
| 31 | +- or - |
| 32 | +
|
| 33 | +Install-Package JsonApiDotnetCore |
| 34 | +``` |
| 35 | + |
| 36 | +### Define Models |
| 37 | + |
| 38 | +Define your domain models such that they implement `IIdentifiable<TId>`. |
| 39 | +The easiest way to do this is to inherit `Identifiable` |
| 40 | + |
| 41 | +```c# |
| 42 | +public class Person : Identifiable |
| 43 | +{ |
| 44 | + [Attr("name")] |
| 45 | + public string Name { get; set; } |
| 46 | +} |
| 47 | +``` |
| 48 | + |
| 49 | +### Define DbContext |
| 50 | + |
| 51 | +Nothing special here, just an ordinary `DbContext` |
| 52 | + |
| 53 | +``` |
| 54 | +public class AppDbContext : DbContext |
| 55 | +{ |
| 56 | + public AppDbContext(DbContextOptions<AppDbContext> options) |
| 57 | + : base(options) { } |
| 58 | + |
| 59 | + public DbSet<Person> People { get; set; } |
| 60 | +} |
| 61 | +``` |
| 62 | + |
| 63 | +### Define Controllers |
| 64 | + |
| 65 | +You need to create controllers that inherit from `JsonApiController<TEntity>` or `JsonApiController<TEntity, TId>` |
| 66 | +where `TEntity` is the model that inherits from `Identifiable<TId>` |
| 67 | + |
| 68 | +```c# |
| 69 | +public class PeopleController : JsonApiController<Person> |
| 70 | +{ |
| 71 | + public PeopleController( |
| 72 | + IJsonApiContext jsonApiContext, |
| 73 | + IResourceService<Person> resourceService, |
| 74 | + ILoggerFactory loggerFactory) |
| 75 | + : base(jsonApiContext, resourceService, loggerFactory) |
| 76 | + { } |
| 77 | +} |
| 78 | +``` |
| 79 | + |
| 80 | +### Middleware and Services |
| 81 | + |
| 82 | +Finally, add the services by adding the following to your Startup.ConfigureServices: |
| 83 | + |
| 84 | +```c# |
| 85 | +public IServiceProvider ConfigureServices(IServiceCollection services) |
| 86 | +{ |
| 87 | + // add the db context like you normally would |
| 88 | + services.AddDbContext<AppDbContext>(options => |
| 89 | + { // use whatever provider you want, this is just an example |
| 90 | + options.UseNpgsql(GetDbConnectionString()); |
| 91 | + }, ServiceLifetime.Transient); |
| 92 | + |
| 93 | + // add jsonapi dotnet core |
| 94 | + services.AddJsonApi<AppDbContext>(); |
| 95 | + // ... |
| 96 | +} |
| 97 | +``` |
| 98 | + |
| 99 | +Add the middleware to the Startup.Configure method. Note that under the hood, |
| 100 | +this will call `app.UseMvc()` so there is no need to add that as well. |
| 101 | + |
| 102 | +```c# |
| 103 | +public void Configure(IApplicationBuilder app) |
| 104 | +{ |
| 105 | + app.UseJsonApi(); |
| 106 | +} |
| 107 | +``` |
| 108 | + |
| 109 | +### Seeding the Database |
| 110 | + |
| 111 | +One way to seed the database is in your Configure method: |
| 112 | + |
| 113 | +```c# |
| 114 | +public void Configure( |
| 115 | + IApplicationBuilder app, |
| 116 | + AppDbContext context) |
| 117 | +{ |
| 118 | + context.Database.EnsureCreated(); |
| 119 | + if(context.People.Any() == false) |
| 120 | + { |
| 121 | + context.People.Add(new Person { |
| 122 | + Name = "John Doe" |
| 123 | + }); |
| 124 | + context.SaveChanges(); |
| 125 | + } |
| 126 | + // ... |
| 127 | + app.UseJsonApi(); |
| 128 | +} |
| 129 | +``` |
| 130 | + |
| 131 | +### Run Migrations |
| 132 | + |
| 133 | +``` |
| 134 | +dotnet ef migrations add AddPeople |
| 135 | +dotnet ef database update |
| 136 | +``` |
| 137 | + |
| 138 | +### Start the Ap |
| 139 | + |
| 140 | +``` |
| 141 | +dotnet run |
| 142 | +curl http://localhost:5000/people |
| 143 | +``` |
| 144 | + |
0 commit comments