From cb64dab3a80bb7b9a6732199e6cf8cd095dd7d79 Mon Sep 17 00:00:00 2001 From: Robert Wallach Date: Mon, 5 Feb 2018 14:58:08 -0600 Subject: [PATCH] Update how-to-create-models.md --- articles/modeling/how-to-create-models.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/articles/modeling/how-to-create-models.md b/articles/modeling/how-to-create-models.md index 752c9cd..d3dbad4 100644 --- a/articles/modeling/how-to-create-models.md +++ b/articles/modeling/how-to-create-models.md @@ -1,3 +1,16 @@ +# Models + +## What +A model contains common reusable information that can be referenced in your endpoint definitions or other models in your API design. The resources or endpoints in your API project might contain duplicate structures and response objects. Models reduce this duplication by helping you extract and define common resources making your project easier to maintain. + +## Best Practices + +### Avoid Cluttered APIs +When you have several endpoints with the same structure, objects, and properties, your API design is untidy. Ensure that you extract reusable artifacts and build them as pragmatic models referenced by other resources within your API project. + +### Use a Design First Approach +A design first approach helps create neat and consistent models. It will take longer, but it ensures you built an effective API that is easy to understand and maintain. + # How to Create Models using the Stoplight Modeling Editor 1. Create a new API project (link on how to create a new project goes here) 2. For this example we will be referring to endpoints created for a fictional Pet Store as listed below