This could be a cloud-based platform like Google Workspace, Microsoft Teams, or Slack. You could also use project management tools like Jira, Asana, or Trello to track tasks and progress.
Create a Dedicated Space for the API Project
Whether it's a dedicated channel on Slack or a project on Jira, create a separate space for your API design project.
Invite Team Members
Make sure all relevant team members have access to this workspace. This may include developers, project managers, UX designers, testers, and even stakeholders from non-tech departments who might use or be impacted by the API.
Set Up Notification Settings
To ensure timely communication, configure notification settings. Ensure that members are alerted for important updates, but also prevent notification overload.
Share Key Resources and Documents
Upload or link all important resources such as the API's requirements document, design guidelines, sketches, etc. Make sure everyone has access to these materials.
Facilitate Regular Updates and Discussions
Encourage team members to post regular updates on their progress, raise questions, share ideas, and discuss problems. This encourages active participation and helps keep everyone in the loop.
Organize Files and Conversations
Keep your workspace organized. Use threads in Slack, or similar features in other tools, to keep conversations focused. Regularly archive outdated documents and messages.
Use Tools for Collaborative Editing
Use collaborative editing tools like Google Docs or Confluence to jointly work on documents like the API design specification or the API's documentation. This allows for real-time collaboration and feedback.
Set Clear Expectations
Ensure everyone knows what they're expected to do within the workspace. This includes how often they should check in, what they should report, and what sort of discussions are encouraged or discouraged.
Seek Feedback
Regularly ask for feedback on how the workspace is helping the team. Are there tools they wish they had? Are there ways the space could be organized better? Use this feedback to continually improve your workspace.
Identify Core Objects Begin by identifying the primary objects or entities that are part of your application domain. For example, in an e-commerce app, core objects might be Users, Products, Orders, Reviews, etc.
Define Relationships Define how these resources relate to each other. An Order, for instance, might be related to a User (who makes the order) and a Product (what is being ordered).
Specify Resource Attributes For each resource, identify the attributes that need to be included. For example, a User might have attributes like username, email, password, etc., while a Product might have attributes like id, name, description, price, etc.
Determine Nested Resources Determine if there are any nested resources. Nested resources are resources that logically exist within another resource. For example, an Order might contain multiple OrderItems.
Decide On Read-only Resources Some resources or attributes of a resource might be read-only. For instance, in the case of an Order, once it's placed, it might be that its status can only be updated internally and not via the API.
Consider Pagination and Filtering For resources that can return a large number of items, consider how you'll implement pagination and filtering. This can make it easier for API consumers to work with your data.
Think About Future Needs Consider any future needs that might arise. Are there resources that you might need to expose in the future? Can your current design accommodate those needs?
Make a Rough Sketch Sketch out your resources, attributes, and relationships. This can be a simple text-based document, or a more visual diagram, whatever works best for you.
Get Feedback Share your design with potential users of the API and others in your team. Get their feedback and make any necessary adjustments. Remember, the design phase is the best time to make changes - it's much harder once you've started to write code!
Document Your Resources Once you're happy with the design of your resources, make sure to document them properly. This should include each resource, its attributes, the expected data types for each attribute, and how the resources relate to each other. This will form a crucial part of your API's overall documentation.
The main objects for our e-commerce API could be Users, Products, Orders, and Reviews.
Define Relationships
Users can place multiple Orders. Each Order can contain multiple Products. Users can also leave Reviews for Products.
Specify Resource Attributes
For the User object, attributes could include id, name, email. For the Product object, attributes could include id, name, description, price.
Determine Nested Resources
An Order object might contain nested OrderItem objects, each representing a specific product in the order, with attributes like product_id, quantity, price.
Decide On Read-only Resources
The Order's total_amount could be a read-only attribute, calculated from the sum of all OrderItem price multiplied by quantity.
Consider Pagination and Filtering For the Product resource, you might allow users to retrieve products in pages of 10, and provide filtering options like price_range, category, etc.
Think About Future Needs
If you're considering adding a feature like wishlists, you could design the User and Product resources in a way that could accommodate a Wishlist resource that links the two.
Make a Rough Sketch You might sketch out your API as follows:
/users - returns a list of users
/users/{id} - returns details of a specific user
/products - returns a list of products
/products/{id} - returns details of a specific product
/orders - returns a list of orders
/orders/{id} - returns details of a specific order, including OrderItems
Get Feedback Share your design with your development team and a few key stakeholders. Adjust your design based on their feedback.
Document Your Resources You might document the Product resource as follows:
Resource Product
Attributes:
id (integer, read-only)
name (string)
description (string)
price (decimal)
Relationships:
Reviews A product can have many reviews
Orders A product can be part of many orders, via OrderItems
Endpoints:
/products - returns a list of products
/products/{id} - returns details of a specific product
The base of each endpoint should be a plural noun, not a verb. For instance, use /orders instead of /getOrders or /createOrder.
Path Variables to Identify Specific Resources
If you want to refer to a specific instance of a resource, use a path variable. For instance, to get information about a specific order, you might use something like /orders/{id}.
Path for Hierarchical Relationships
When resources have a hierarchical relationship, it can be useful to express this in the URI. For example, to access all the orders by a specific user, you could use /users/{id}/orders.
Consider Using Query Parameters for Filtering, Sorting, and Pagination
Query parameters can be used to specify how a list of resources should be filtered, sorted, or paginated. For instance, /products?category=electronics&sort=price_asc&page=2.
Use Consistent Case and Separator Styles
Whether you use camelCase, snake_case, kebab-case, or any other style, be consistent across all your URIs.
Avoid Using CRIDs
Avoid using internal IDs or other implementation details that might change over time. Instead, try to use identifiers that are meaningful to the API users.
Avoid Using File Extensions
Instead of using file extensions to indicate the format of the returned data, rely on the HTTP headers (Content-Type for requests and Accept for responses).
Be Concise
Avoid unnecessary words and keep your URIs as short as possible. This makes them easier to read and remember.
Test Your URIs
Ask someone unfamiliar with your API to try to guess what each URI does based on its structure. This can be a good way to test whether your URIs are intuitive.
Document Your Design
Once you have determined your URI design, document it, providing information on the naming conventions, structure, and any other details that will help users understand how to interact with your
Checklist: REST APIs