I am struggling to understand how AWS API Gateway wants me to organise my APIs such that versioning is straightforward. For example, let's say I have a simple API for getting words from a dictionary, optionally filtering the results by a query parameter. I'd like to have v1 of this be available at:
https://<my-domain>/v1/names?starts-with=<value>
However, the closest I can get API Gateway is at
https://<my-domain>/names/v1?starts-with=<value>
... which is quite backwards.
What I've got in the console is "Names API" with a "v1" resource supporting a GET method. I also have my custom domain setup to map a base path of "names" to "Names API" and stage "test". The Base path must be unique so putting "v1" there is only a short-term win; once I create my second API (e.g. Numbers API) it'll have a v1, too, and I won't be able to create a second mapping.
Any and all help is greatly appreciated as I'm out of ideas now.
Do not create the version path (/v1) as a resource in your API. Instead, simply call you API "Names V1" and start creating the resources (/names). When you want to make a breaking change and create a new version of the API, we recommend you create an entirely new API called "Names V2". Once again, simply create your resources without the version path.
To bring the two APIs together, you can use custom domain names. A custom domain name in API Gateway includes both a fully qualified domain name and a base path. Create two custom domain names:
myapi.com/v1 -> points to the prod stage of the Names V1 API
myapi.com/v2 -> points to the prod stage of the Names V2 API
This way you can keep bug-fixing v1 while making changes to v2 and deploy the two APIs independently. The custom domain name will bring them together and make them appear under the same domain (myapi.com/v2/names).
Hope this helps.
Related
Reading through GoDaddy's domains endpoint documentation ( https://developer.godaddy.com/doc/endpoint/domains ) am trying to use GoDaddy's API to update DNSSEC records (DS records to be more precise). Very few examples (found none actually) are out there showing how to actually do that.
The above documentation does seem to mention a "model" called DomainDnssec (same URL as above) which does refer to values and their types that need to be either POST'ed or GET'ed using one of the API URLs but it's not clear to me which one. What is "model" in that context anyway (literally just a description of data types that have to be posted or received using particular API endpoints? this is not clear to me either and documentation is silent about that)?
As much as I do not have an issue with using API in general (all set up and working, together with finding out infamous customerId which most folks confuse with shopperId), I'm having a hard time finding which API call allows interacting with DNSSEC on GoDaddy's API.
I did not try much yet as none of the actions (API calls) within the API domain namespace documentation seems related particularly to DNSSEC.
===an update
It seems that in the Action model (https://developer.godaddy.com/doc/endpoint/domains#/), there is a reference to API calls that do not seem to be documented:
DNSSEC_CREATE - Request to create DNSSEC record for the domain via PATCH /v2/customers/{customerId}/domains/{domain}/dnssecRecords
DNSSEC_DELETE - Request to delete DNSSEC record for the domain via DELETE /v2/customers/{customerId}/domains/{domain}/dnssecRecords
Not sure why this call is not explicitly documented among other v2 API calls. An overlook? Still not sure how to build API calls allowing to update DNSSEC records.
I am creating Cars store in Asp.Net for my school.
I built an Api Method:
[HttpGet("api/brands/{brandName}/models")]
public IActionResult Get(string brandName)
{
{
var model = _context.getBrandByName(brandName);
return Ok(model.Models.ToList());
}
}
An it works when I am checking it with Postman.
Now I would like User to choose brandName from selection list in the website and show him avaliable models.
In other words I dont know how to use this Api to get Data displayed.
Any help will be strongly appreciated
RESTful Web services are one way of providing interoperability between computer systems on the Internet. REST-compliant Web services allow requesting systems to access and manipulate textual representations of Web resources using a uniform and predefined set of stateless operations.
from Wikipedia.
This means, the REST API's only concern is to provide the data to work in a uniform and predefined set of operations, where those operations take the HTTP Verb that was used in consideration.
in your example, your GET route, should only be api/brands/{brandName}
the default in rest api, http verbs say:
GET - getting one element or a list
POST - creating
PUT - updating
DELETE - removing
in your application, the best approach would be something like:
GET /api/brands will get ALL existing brands
GET /api/brands/<brand_name> will get just one brand
POST /api/brands will create a new brand
PUT /api/brands will edit an existing brand
DELETE /api/brands will delete an existing brand
from your question:
Now I would like User to choose brandName from selection list on the website
the website would then request a GET to the route /api/brands to get the list of all of the brands.
This is the REST API part, it concerns ONLY in providing the right data to the system that request it.
if you want to create a website in order to CONSUME this data, you can easily create a new web project in your solution and request the data that the API provides, making the Website completely "blind" from where the data comes from, as it only asks for the data itself.
Making the whole system much easier for updated and maintainability.
In other words I dont know how to use this Api to get Data displayed.
The main purpose of REST API is to expose data not to display it by using any kind of UI framework.
If you think you need to manage the full stack of your application end-to-end. I mean from User interface to your database then you must think at implementing the V of the MVC pattern bu return a view and not just a data. ASP.Net Core can help you with that. Follow this tutorial, it explains a lot about this pattern in ASP.Net Core MVC.
Our product (Yoke.io) integrates Evernote through REST API. We need to generate direct URL link to a specific notebook, note or tag so that user can click the link to access them.
However, current URL format contains parameters named "ses", "sh" and "sds" in addition to the ids for notebook/note/tag. I have no idea what these parameters mean and if they are different for different users, platforms, etc.
For example, if I want to access a notebook with id "3ec5f3c1-bd4d-4f94-b924-367b13eaf3bc", and generate the following links:
https://www.evernote.com/Home.action#b=3ec5f3c1-bd4d-4f94-b924-367b13eaf3bc
https://www.evernote.com/Home.action#b=3ec5f3c1-bd4d-4f94-b924-367b13eaf3bc&ses=4&sh=1&sds=5&
The first link (#1) won't work but the second link (#2) works.
I could hard-code "ses", "sh" and "sds" parameters in the URL but my feelings is that these parameters will change for different users.
Could anyone explain more on what are these parameters for and how I can generate a direct URL link to a specific Evernote notebook/note/tag?
Thanks a lot for your help.
Regards,
Tao
ses, sh and sds are hash parameters we use when serializing the state of the web client. If you try manipulating the hash parameters to get the web client into a certain state, note that these are undocumented APIs and are subject to change at any time. That said, they won't change super often.
None of those three parameters will change on a per-user basis, they represent the "view" of the client you're in at the time. The simplest way to get a url in the format you like is to navigate to that view in the web client, copy the hash, and replace note and/or notebook guids in the url (b for the notebook guid and n for the note guid).
I'm struggling to find an answer to this (perhaps because I'm not asking the question properly) ...
I'm building API to expose resources for a basic social networking service I'm creating.
My understanding is that the structure of URLs in an API is essentially a hierarchy, directory like structure. I think that means I can have multiple endpoints to reach the same resources or collections of resource links.
For example:
I have an endpoint
www.domain.api.org/users/{:uid}/posts
Which will return all posts sent by the user or that the user is tagged in. Seems ok, but what if I have an endpoint such as:
www.domain.api.org/posts
Which when hit with a http GET will return all public posts (i.e. all users' posts plus his friends' and public posts).
The difference is that the first URL points to user owned resources whereas the second to public ones (of which the users posts are included of course)
Are these okay or am I doing it the wrong / less sensible way?
To reiterate, can I have multiple endpoints which point to different contexts/views of the same resource?
Basically multiple endpoints for the same resources should be avoided. However in this particular case it does make sense.
What you can do is to introduce optional query param userId to the following endpoint:
www.domain.api.org/posts/?userId=<userId>
If this substitutes the first endpoint you mentioned that's the way to go.
I would like to add ontop of #Opal's answer.
Are these okay or am I doing it the wrong / less sensible way?
Ideally, like Opal mentioned, you would use queryParams in your url. For many applications I have build, I don't know the uids returned from the api beforehand, so selecting an item and passing it inside my url as a query parameter makes sense. But it also has the added benefit of having your key inside your url, allowing you to bookmark it, pass the url to another user and they will automatically see the same data you want them to see.
To iterate: Is your current implementation wrong? No, but ideally you would use a combination of both route parameters are query parameters to achieve this
To create an endpoints, you have to be sure that you have these information at once:
Name of the endpoint
Status: activate or not (required) - is the endpoint activated or disable
Service profile (required) - ID of the Service Profile assigned to the endpoint.
Tariff profile (required) - ID of the tariff Profile assigned to the endpoint.
You can add another optional informations, and be sure of the structure of your endpoint.
Hope this helps you.
I am trying to figure out the "right" implementation for an url structure for an application with multitenancy support and shared resources.
Resources: Users, Projects
The URL schema is
host/api/tenant_id/resource[/id][/subresource][/id]
User A (width id = 1) gets a collection of his projects at
GET http://example.com/api/1/projects/
User A creates a new project, readable by
GET http://example.com/api/1/projects/2
Now User A gives another User B (id = 2) access to project 2.
User B would like to see a collection of all projects related to his account via:
GET http://example.com/api/2/projects/
Should the shared project (id = 2) be in this collection besides those, User B created by himself? Or is there a better naming structure for shared resources?
Focusing on the design of URL structures is actually a no-go for RESTful architectures. Roy Fielding:
A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server).
See also this answer.
For your specific problem I would return a list of (basically arbitrary) hypertext links to the projects the user has access to. The links would contain attributes making it clear, whether the project is »owned« or »accessible« by the user. To improve readability you could design your resource URLs as
http://example.com/user/{user id}
http://example.com/project/{project id}
The representation of user after a GET http://example.com/user/2 would contain the list of links like
<a href="http://example.com/project/1" class="owned"/>
<a href="http://example.com/project/2" class="access-permitted"/>
The HATEOAS principle is inherent to REST and makes most »how do I design my URIs« questions obsolete:
The principle is that a client interacts with a network application entirely through hypermedia provided dynamically by application servers. A REST client needs no prior knowledge about how to interact with any particular application or server beyond a generic understanding of hypermedia.
Maybe one advantage can be in using tenant info in the path. In such way we can easily have for example the lists of objects.
Querying the uri on get /tenant-id/projects
We can have a list of of projects for each entry tenant.
How can be get without tenant info into url?
My 2 cents