Understanding RESTful API Design: Principles, Examples, and Best Practices

Table Of Content

• API Versioning
• Versioning Strategies
• Versioning through URI Path
• Getting Started with Next.js API Routes: A Comprehensive Guide
• Error!

When it comes to naming resources in REST APIs, consistency is key. A crucial aspect of this is the use of nouns as ‘resource identifiers’ in URIs to specify the contents of the resource clearly. Consistent naming conventions for these resource identifiers facilitate predictability and ease of use, leading to fewer errors and quicker developer integration.

API Versioning

You wouldn’t want to be returning an error response with a status code that does not correspond to the error. This is a better approach, the client would know that we are dealing with the collection of data involving users and not just one user. There isn’t a single approach to API design that will work for every organization. The above suggestions are just that — advice and recommendations which can be used or discarded depending on your user case and requirement.

Versioning Strategies

As you can see, we've added the two properties "memberId" and "member" to our records inside the database. This has the huge advantage that we don't have to nest deeper our existing endpoint. The endpoint now becomes less manageable the more nesting we add to it. Therefore it's a good practice to store the URI to receive information about a member directly into the record. We've already implemented the endpoints correctly without using verbs inside the URL, but let's take a look how our URL's would look like if we had used verbs. Every error that gets thrown inside our Workout.createNewWorkout() method will be caught inside our catch block.

Versioning through URI Path

If you have an API style guide, you may be able to use a linter to catch that singular endpoint before it goes live. Consistency leads to a better developer experience and a greater likelihood that your API won’t need major changes. This has also helped avoid the need for "experience APIs" (see response above) layered on top of our API.

We'll also need a record router to catch the specific requests for the records, but we don't need it right now. This could be a great chance for you to implement the CRUD operations for the records with their own routes and train a bit. Chances are high that have we to implement CRUD endpoints for the records as well, because records should be added, updated or deleted in the future as well. In our Crossfit API we will take a look at the creation endpoint and see what errors might arise and how we can handle them. At the end of this tip you'll find again the complete implementation for the other endpoints. Let's go into our workout service and receive the data inside our createNewWorkout method.

RESTful API Designing guidelines — The best practices - hackernoon.com

RESTful API Designing guidelines — The best practices.

Posted: Fri, 25 Mar 2016 07:00:00 GMT [source]

Take close look at the bottom of our comment under "items". We're using "$ref" to create a reference and are referencing the path to our schema we've defined inside our workout file. Typically this definition will be inside your schema or model file where you've defined your database models. Because we've planned to have different versions of our API, the docs will be a bit different, too.

The 5 essential HTTP methods in RESTful API development - TechTarget

The 5 essential HTTP methods in RESTful API development.

Posted: Fri, 25 Aug 2023 07:00:00 GMT [source]

The API queried the database for a table and then searched the table for detailed data. The seller (acting as the API) queried the shelves (the database) for the requested data. This guide is a living document and additions to it will be madeover time as new style and design patterns are adopted and approved. In thatspirit, it is never going to be complete and there will always be ampleroom for the art and craft of API design. This guide applies to both REST APIs and RPC APIs, with specific focus on gRPCAPIs. GRPC APIs use Protocol Buffers to define their API surfaceand API Service Configuration to configure their API services, includingHTTP mapping, logging, and monitoring.

SSL/TLS security is a common and affordable way to make sure every request and response is encrypted over the channels. There are methods to improve API design — like following RESTful practices. But time and again we are seeing customers unknowingly program minor inconveniences into their APIs.

So basically a REST API is simply creating a medium that involves a set of rules that gives different programs access to communicate with each other. Monetize your AI model by transforming it into an AI API, creating new revenue streams by integrating your AI capabilities into other applications. Documenting changes in each API version is critical for effectively managing versioning. Special characters in URIs can be likened to bumps on a smooth road, causing confusion and increasing technical complexity.

All great things start with a plan, including building an API. Imagine an external user wants to query the user table by sending an ID, and the API method you designed uses the POST method. This will limit the users' queries as the end-user isn't adding or creating data, and the user can not query the way they should be able to. As data sometimes contains sensitive information like credit card information, we have to keep the communication between server and client totally private.

When something goes wrong (either from the request or inside our API) we send HTTP Error codes back. I've seen and used API's that were returning all the time a 400 error code when a request was buggy without any specific message about WHY this error occurred or what the mistake was. If you try to add the same workout for a second time, you still receive a 201 status code, but without the newly inserted workout. Let's think about an endpoint where we need to receive JSON data from the client.

10 best practices for REST API design LogRocket Blog

Table Of Content

• Assign proper API versioning
• Endpoint paths should be written with nouns rather than verbs
• You’ve made it this far. Let’s build your first application
• Describe resource functionality with HTTP methods
• How does API design support the API-first development model?

Multiple network calls slow down the process and creates higher connection overhead — which means higher operational costs. This is why it’s so important to minimize the number of API calls. You’ll want to keep your entire team updated as you make design decisions together. Your OpenAPI spec is your single source of truth, so make sure it is available in a place where everyone can see revisions and discuss changes.

Assign proper API versioning

You can send the spec document itself, or use tools to prototype your API or documentation. You could generate mock servers based on your spec, as described in another section, and have your consumers make live calls. While OpenAPI v3 is the most recent version of OpenAPI, it replaced OpenAPI v2 - previously known as Swagger. The newer version provides a simpler way to describe APIs, while also offering more flexibility.

Endpoint paths should be written with nouns rather than verbs

Mocks can also be used alongside API tests, which can be run manually, on a schedule, or automatically within CI/CD pipelines. There are tons of built-in HTTP status codes available to properly handle errors and convey the result of a client’s request. In this code, the handler checks if the req.method is 'GET'.

You’ve made it this far. Let’s build your first application

If you are planning to make changes to your API, always make sure to assign the proper version so that the client end does not break. You should provide options for clients to either continue using the previous version or try the newer one. A well-designed REST API should always accept and receive data in the JSON format. In this article, we’ll take a deeper look at the best practices for designing REST APIs to ensure the best performance possible.

We've defined all the properties that make up a workout including the type and an example. To read further and get some more best practices on that topic, I can suggest reading this article. There's one important thing I'd like to note here when it comes to caching. While it seems to solve a lot of problems for you, it also can bring some problems into your application. Once our cache is empty again (after two minutes) it has to be filled again.

OWASP Updates Top 10 API Security Risks - Security Boulevard

OWASP Updates Top 10 API Security Risks.

Posted: Wed, 16 Aug 2023 07:00:00 GMT [source]

We don’t want errors to bring down our system, so we can leave them unhandled, which means that the API consumer has to handle them. The only exception is if we’re trying to send and receive files between client and server. Then we need to handle file responses and send form data from client to server. A REST API is an application programming interface architecture style that conforms to specific architectural constraints, like stateless communication and cacheable data. API-first is a development model in which applications are conceptualized and built with services that are delivered through APIs. Whereas companies that take a code-first approach might view APIs as afterthoughts, API-first companies design their APIs before they develop their applications.

How does API design support the API-first development model?

When you use OpenAPI to design your API, it becomes part of your workflow. That means as soon as you have even a single potential endpoint of your API described, you can begin to gather feedback and piece together how your API will be used. Rather than toiling away in an API silo, your API description allows for collaboration with colleagues and across departments. You can work the API description into your approval processes, so everyone is on the same page with its progress. Try Stoplight Platform to bring a design-first approach to your API workflow. The model you expose through an API is the conceptual model of the problem domain as seen by a client.

Apigee — Google Cloud’s native API management platform — helps you build, manage, and secure APIs — for any use case, scale or environment. Get started with Apigee today or check out our documentation for additional information. Your goal should be helping your customers be successful with your data, as quickly and easily as possible. Occasionally, that may mean breaking some "rules" of REST to offer simpler and more elegant interfaces.

Make use of REST

When I start building an API and there are no particular reasons to use a cache straight away, I leave it out and see what happens over time. When reasons arise to use a cache, I can implement it then. We can define a new cache by calling apicache.middleware and use it as a middleware inside our get route.

One thing that might go wrong is the database insertion Workout.createNewWorkout(). I like to wrap this thing in a try/catch block to catch the error when it occurs. Let's go one layer deeper into our workout service and see what potential errors might occur. A developer who is consuming the API is now better informed about what to look for.

On top of that it gets the member id and the endpoint to fetch information about that member. As you can see, logical nesting makes sense when you have resources that can be tied together. Theoretically you can nest it how deep you want, but the rule of thumb here is to go three levels deep at a maximum. For example, there is a workout where you have to do a certain order of exercises as quickly as possible. We record the times for all members to have a list of the time for each member who completed this workout.

Resist the temptation to manipulate objects as strings, or use regular expressions to get the data you need. Programmers can still maintain language flexibility, but they will use the library to either extract data from or add data to the payload. Below is a simple client program in Python that gets a response object, examines it for an error, and prints a specific element from the JSON. The most important takeaways for designing high-quality REST APIs is to have consistency by following web standards and conventions.

Bug corrections are difficult and updates become a nightmare. Poor server-side coding will result in increased maintenance costs.There are many commercial offerings that assist with API design but again, there is no substitute for common sense. Before getting started with a REST API design, you need a Functional Specification. It might include a few mockup screenshots and information flow diagrams, but it is essentially a high-level document. By contrast, the API design gets into the nitty-gritty of how it works.

The World's Largest Cruise Ship Is Nearly 1,200 Feet Long Smart News

Table Of Content

• The 30 Largest Cruise Ships in the World Ranked
• Fuel Spills
• Royal Caribbean Harmony of the Seas
• MSC Seascape
• Royal Caribbean Oasis of the Seas

On the other hand, family-focused cruises prioritize a plethora of activities, requiring larger ships with vast entertainment areas, multiple dining options, and expansive pool decks. The transition from ocean liners to dedicated cruise ships marked a significant shift. These new vessels were no longer solely about getting from Point A to Point B. Icon has more than 40 other places to dine and drink, more than half being new to the fleet. The food that comes with no extra charge can be iffy on mainstream cruise ships, but what was served on the preview sail was quite good overall, and that includes the main dining room and Windjammer buffet.

The 30 Largest Cruise Ships in the World Ranked

From intimate yachts to city-like behemoths, there’s a vessel for every type of cruiser. The brand ethos and the target demographic play a pivotal role in determining ship size. Luxury liners, often catering to an exclusive clientele, might opt for smaller sizes to provide a more intimate, personalized experience. At its core, the length of a cruise ship can vary greatly based on its purpose, design, and target audience. The ship will be equipped with a special grooming robot that will clean the hull whenever it’s in port to help reduce drag and improve fuel efficiency by 3 to 4 percent, reports TTG Media’s Charlotte Cullinan.

Fuel Spills

This cruise ship boasts a weight of 236,857 GT and has 16 passenger decks. Its length is 1,188 feet and accommodates an impressive 6,988 passengers. Passengers appreciate that these cruise ships provide a balance between large ship amenities, fewer crowds, and intimate spaces. There is an abundance of features and entertainment on these ships, but the difference is that they do not contain many extravagances. The trade-off for a scaled-back ship environment is that these ships go to more exotic ports that larger vessels are unable to visit due to size.

Royal Caribbean Harmony of the Seas

The Canadian government lifted a cruise ship ban in Canadian waters late last year. Norwegian Cruise Line (NCL) Encore is a part of the four-ship Breakaway Plus-class, a class known for mimicking small cities with numerous outdoor activities. Iona includes 2,614 cabins and 15 decks accessible to guests.

MSC Seascape

The ship will begin offering five-to-seven night cruises from Florida to the Caribbean in March, and Western Mediterranean cruises from Barcelona and Rome will begin in May. And if those perks aren’t enough, the “Suite Neighbourhood” offers private lounges and VIP pool areas for those guests who upgrade to a larger room. While size will always play a role in the cruise experience, the industry’s adaptability, innovation, and commitment to sustainability will steer its course forward. For avid cruisers and curious onlookers alike, the future promises waves of excitement, discovery, and more sustainable adventures on the horizon. The cruise industry, much like any other, evolves in response to technological innovations, environmental concerns, and passenger preferences.

Royal Caribbean Oasis of the Seas

The signature zone, if we have to choose just one, is AquaDome, named for the 363-ton apparatus made primarily of glass and steel. Here on decks 14 and 15 is a next-gen edition of the water and aerial show staged on Oasis-class ships, and it’s spectacular. ” makes the most of an amphitheater that is a marvel unto itself. Bringing the show indoors is better for the audience and cast, some of whom are asked to dive from 60-foot-high platforms or rhythmically perform while tethered overhead. P&O Cruises held its spot on the top ten list of largest cruise ships in the world with an aptly named ship.

Adaptive Design

Venturing on a smaller cruise ship often feels like embarking on a private journey, where the world seems more intimate, and the experiences more personal. Sailing on a mammoth cruise ship can be an exhilarating experience, much like exploring a small floating city. These ships, with their extensive range of facilities and attractions, have their distinct set of pros and cons. Ever stood at a port and wondered why one cruise ship dwarfs another? Let’s dive into the reasons behind the diverse lengths of these vessels.

The world's largest cruise ship has set sail from Miami, Florida, on its maiden voyage. At long last, the world’s largest cruise ship is set to embark on its maiden voyage. Carnival Mardi Gras first debuted in 1972 and was a trailblazing ship. Its preliminary focus was on festive fun for all guests (hence the name), which was unlike any other cruise ship at the time.

Icon of the Seas: World's largest cruise ship sets sail from Miami - BBC.com

Icon of the Seas: World's largest cruise ship sets sail from Miami.

Posted: Sun, 28 Jan 2024 08:00:00 GMT [source]

World Europa is the first of four total ships in MSC's World-class fleet, with the second ship World America set to launch in 2025. Royal Caribbean's Symphony of the Seas slips to the fourth position this year, having been the biggest cruise ship in the world from 2018 to 2022. It has 16 guest decks (18 total decks) along with 2,759 staterooms.

Larger ships often have the space to house a wider array of dining, entertainment, and recreational facilities. However, the quality and uniqueness of these amenities can vary across cruise lines. While there isn’t a strict maximum length set universally, ship sizes are often restricted by the capabilities of shipyards, port facilities, and maritime safety standards. Generally, larger ships with wider beams can offer better stability in rough seas. However, stability also depends on the ship’s draft, hull design, and stabilization systems. However, the length can vary significantly based on the ship’s design, purpose, and the cruise line it belongs to.

It first set sail in 2019 and has 18 decks (15 available to guests) and 2,217 cabins. MSC Meraviglia is the first ship in MSC's Meraviglia-class and received the "8 Golden Pearls" award, which recognizes sustainable and environmental stewardship. This meritable ship has 18 decks, 15 of which are accessible to guests, and 2,244 total staterooms. MSC Grandiosa is a part of the Meraviglia Plus-class, which currently has five sailing ships. Onboard, there are 18 decks (15 of which are passenger-accessible) and 2,405 staterooms onboard.

Arvia is Latin for “from the seashore.” Arvia was launched in 2022 and features 19 decks (15 passenger-accessible decks). Besides taking on the mantle of largest cruise ship in the world, Icon of the Seas is yet another game changer for Royal Caribbean. Its launch in January 2024 heralds a new ship class loaded with new attractions and iconic spaces. It features 20 decks (18 guest-accessible decks), a record-setting six water slides and the largest swimming pool at sea.

Some ships in this category have been refurbished and offer great value, while others provide a luxury experience. Penner said he hopes that change comes soon, noting that double-vaccination and a negative test result are requirements for virtually everyone on board cruise ships, and robust health and safety plans are in place. The cruise ship length is professionally referred to as LOA (length overall), meaning the maximum length between the two most distant points on its hull. LOA may also include the tip of the bowsprit - the pole extending from the ship's prow (usually on tall sailing ships, yachts, and smaller boats).

Which European cities are trying to cut back the number of cruise ship visits? - Euronews

Which European cities are trying to cut back the number of cruise ship visits?.

Posted: Tue, 16 Apr 2024 07:00:00 GMT [source]

AIDA Cruises AIDAcosma, the second in the Excellence-class, was first released in December 2021. It has 20 decks and 2,626 passenger cabins, which includes suites. Costa Toscana is Costa Smeralda's sister ship, meaning the two ships are identical in size. The second Icon-class ship, Star of the Seas, is set to sail in 2025. As of my last update in 2022, the title belongs to “Symphony of the Seas” by Royal Caribbean, measuring approximately 1,188 feet.

It was the first ship to be awarded the "Blauer Engel," which is a German environmental label given to green-friendly products and services. Launched in 2023, MSC Euribia is among the list of LNG-powered ships that are revolutionizing the industry with cleaner operations as it cruises to mostly European ports of call. Costa Smeralda is the first ship in Costa Cruises' Excellence-class fleet. This premier ship has 20 decks along with 2,614 staterooms and suites onboard. Costa Smeralda was named after a popular tourist destination in Sardinia. Some ports have limitations regarding ship length, draft, or air draft, restricting larger vessels.

Its first voyage was in March 2022, becoming the fifth member of Royal's Oasis-class ships. The aptly named Wonder of the Seas has 18 decks (16 guest-accessible decks), 2,867 staterooms and 19 pools. Icon of the Seas, like its two sister ships scheduled to launch in 2025 and 2026, is designed with five neighborhoods new to the fleet.