Getting Started
-
Install the Prerequisites
-
Docker Desktop
-
Codiac
npm i -g @codiac.io/codiac-cli
1. ### Azure CLI 1. ### Node.js
-
-
Create a new EMPTY git repo
Also, you will be adding your own content, so you will not need to create it with a gitignore or a readme file (though its ok if you do).
GitHub:
Azure DevOps:
Either with a new project or from an existing project
Bitbucket
Important:
Be sure to copy the clone URL because you'll need it in the next step.
-
Create your Codiac API project
-
Open a command line and navigate to the PARENT folder you like to use for development projects
cd ~/dev
-
Initialize a new project into that folder using your clone url
We are going to use the optional
-t
parameter (aka:--projectType
) to specify that we want to initialize as anapi
project type:cod init -t api -c [your-clone-url] ./[target-folder]
Note: replace "[your-clone-url]
" and "[target-folder]
" in that example with the clone url for the new repo you just created and the folder into which you want to clone it.This command will open your project into a new VSCode instance. Give it a minute while installs all the npm packages for the api project type.
-
-
Open the new project in VSCode
Give it a minute while installs all the npm packages for the api project type.
Open a command line window to the root of your new project folder.
-
Set your Identity Tokens
If you are going to be accessing private npm packages, you'll need identity tokens for your package registry(ies) in order to build successfully. In that case, set your identity tokens before building:
cod identity --provider npm --token abc23pdq456e.etcetera.etcetera
Note:
You can always get help on any command by calling it with the
--help
argument, eg:cod identity --help
-
Build
cod build
NOTE: This command creates a newDockerfile
in your project root if you do not already have one. If you want to regenerate your Dockerfile, just delete this file and run build again. -
Run
Bare-metal
(just the api, without a container)
From the VSCode menus, select
Run > Start Debugging
, or hitF5
Container
(using Docker desktop)
cod run or cod run --port [1234]
In both cases logs will write to your output window, and when the api has successfully bootstrapped itself, it will provide you the address at which to access it in the following log message:
apiHost listening on 0.0.0.0:5775...
-
Verify the Run
Verify it by hitting a few of the built-in endpoints using your favorite api client (Postman's a good one)
Version:
GET http://127.0.0.1:1775/version
openApi spec:
GET http://127.0.0.1:1775/openApi
-
Check in your code
Now that you've created your api, and verified that its a good build and run, it is a good time to put a stake in the ground and commit your code.
You can do this with git, but the codiac CLI also provides you several source code commands to keep things simple.
The example below uses the
stage
command with the-c
(aka:--commit
) argument to perform both the stage and commit in the same step.cod stage -A -c "Initial project creation"
See also:
commit
,pull
,push
,branch
,switch
,status
,merge
,sync
-
Add a set of RESTful CRUD endpoints for an entity
Let's say you have a "shoe" entity in your business domain, and you want to enable consumers of your api to create, read, update, and delete it (aka: CRUD).
The ApiDef extensions make easy work of this, and you're going to need to tell them a few things about your shoe entity.
a. Create a class for your shoe and be sure that it implements
IDomainEntity
.
```Typescript export class shoe implements IDomainEntity { constructor(public size: number, public brand: string, public model: string, public gender: string, id?: string) { this.id = id; }public id: string|undefined;
}
b. To enable searching on your entity, you'll need a criteria object that will enable your endpoint consumers parameterize their searches.
Typescript export class shoeCriteria { constructor(public size?: number, public brand?: string, public model?: string, public gender?: string, public id?: string) { } } ``` CONVENTION: Each property on the criteria object will apply to the corresponding property of that name on the domain entity.NOTE: Notice the use of optional properties on the criteria object example... api consumers will set only the properties they want to search on, so you'll want your endpoints to be able to know when a given property is relevant.
See Searching and Criteria for more on supporting searches.
Ok, now that you have your entity and its corresponding criteria object, you're ready to declare a set of CRUD endpoints for it.
Open the constructor for your api definition and declare a crud set...
Typescript this.addCrudsFor<shoe,shoeCriteria>(shoe, "shoecriteria", "/shoes");
As you can see, theaddCruds
method also wants you to declare the route (/shoes
in this case) in addition to the domain entity and its criteria. -
Build and Run
cod build
VSCode > Run > Start Debugging
or hitF5
or
cod run
-
Now let's take a look at your new endpoints
(NOTE: They are automatically documented on the swagger page of your api: GET http://127.0.0.1:1775/openApi)
- Create, CreateMany
POST http://127.0.0.1:1775/shoes/new POST http://127.0.0.1:1775/shoes
- Read, ReadMany
GET http://127.0.0.1:1775/shoes/{id} GET http://127.0.0.1:1775/shoes
- Update, UpdateMany
PUT http://127.0.0.1:1775/shoes/{id} PUT http://127.0.0.1:1775/shoes
-
Delete, DeleteWhere
DELETE http://127.0.0.1:1775/shoes/{id} DELETE http://127.0.0.1:1775/shoes
AND... -
Patch, PatchWhere (there are 3 diff types of patch based on content-type header)
PATCH http://127.0.0.1:1775/shoes/{id} PATCH http://127.0.0.1:1775/shoes
(ok, so it's not just CRUD, it's CRUD-P.... Yay!)
- Create, CreateMany
-
Check in your code
cod stage -A -c "Added show cruds"
-
Publish your image
cod publish
Congratulations!
Hopefully your brain fired off a couple Dopamine hits as you worked thru that quick implementation and watched it snap together. And look at that, you have a fully functional, RESTful, standards-compliant API!
Now that you've enjoyed your little moment of self-actualization, it's time to propel yourself even further: **Check out some more info and examples: